Interactive Explorer

Search and explore 6.7 million material samples

NoteHow It Works

1. Instant (<1s): Pre-aggregated H3 res4 summary (0.5 MB) → 38K colored circles
2. Zoom in: Automatically switches to res6 (112K) then res8 (176K) clusters
3. Zoom deeper (<120 km): Individual sample points from 63 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.

SESAR OpenContext GEOME Smithsonian

Stats ▸

Loading...Resolution

0Clusters Loaded

0Samples Loaded

-Load Time

SESAR OpenContext GEOME Smithsonian

Heatmap (filtered density)

Material ▾

Loading...

Sampled Feature ▾

Loading...

Specimen Type ▾

Loading...

Material / feature / specimen filters apply at sample zoom level — zoom in or click a cluster.

Link copied!

Loading H3 global overview...

Click a cluster or sample on the globe

Samples table

Loading samples matching the current filters...

Cesium.Ion.defaultAccessToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIwNzk3NjkyMy1iNGI1LTRkN2UtODRiMy04OTYwYWE0N2M3ZTkiLCJpZCI6Njk1MTcsImlhdCI6MTYzMzU0MTQ3N30.e70dpNzOCDRLDGxRguQCC-tRzGzA-23Xgno5lNgCeB4';

R2_BASE = (() => {
    const DEFAULT = "https://data.isamples.org";
    const raw = new URLSearchParams(location.search).get('data_base')
        || (typeof localStorage !== 'undefined' && localStorage.getItem('ISAMPLES_DATA_BASE'))
        || DEFAULT;
    // The base is interpolated into `read_parquet('${url}/...')` in many queries, so
    // a value containing a single quote (or backslash) could break out of the SQL
    // string literal (Codex P2 — data_base is user-controllable via ?data_base= /
    // localStorage). Reject any such value and fall back to the default. Also require
    // an http(s) or root-relative form (httpfs only range-fetches absolute http(s);
    // a relative is resolved against origin below).
    if (/['"\\\x00-\x1f]/.test(raw) || !(/^https?:\/\//.test(raw) || raw.startsWith('/'))) {
        if (raw !== DEFAULT) console.warn('Ignoring unsafe/invalid data_base override; using default origin:', raw);
        return DEFAULT;
    }
    // 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_202608_h3_summary_res4.parquet`
h3_res6_url = `${R2_BASE}/isamples_202608_h3_summary_res6.parquet`
h3_res8_url = `${R2_BASE}/isamples_202608_h3_summary_res8.parquet`
// #300: the _v2 lite carries h3_res4/h3_res6 (for in-browser filtered-cluster
// aggregation). A new filename rather than overwriting the original keeps the
// immutable-cache contract intact (isamples_YYYYMM_*.parquet is served
// immutable/1-yr) — every visitor fetches fresh data, no cache purge. The next
// generation builds res4/res6 into the canonical name natively (build change),
// so this _v2 suffix is a one-off retrofit for 202608.
//
// #311: _v3 rebuilds place_name/result_time via the SamplingEvent/
// SamplingSite graph traversal (the fix in build_frontend_derived.py) — _v2's
// place_name/result_time were 100% NULL, a dead read off MaterialSampleRecord
// directly (see build_frontend_derived.py's `samp` CTE for the traversal).
// Rebuilt from the SAME wide.parquet as _v2 (row-count and per-source
// min/max-pid verified identical against the live wide before rebuilding),
// so this is a pure column-content fix, not a data-vintage change. Same
// immutable-cache reasoning as _v2: new filename, never overwrite.
lite_url = `${R2_BASE}/isamples_202608_samples_map_lite_v3.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_202608_wide.parquet`
// v2 carries object_type alongside material and context (URI-string columns).
facets_url = `${R2_BASE}/isamples_202608_sample_facets_v4.parquet`
facet_summaries_url = `${R2_BASE}/isamples_202608_facet_summaries.parquet`
// Pre-aggregated single-filter cache for fast cross-filtered facet counts.
cross_filter_url = `${R2_BASE}/isamples_202608_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_202608.parquet`

// #281/#282/#291 facet hierarchy — SHIPPED, default ON. Material, Sampled Feature
// (context) and Specimen Type (object_type) render as expandable trees backed by the
// hierarchy artifacts below; source stays flat. `?facets=flat` is the kill-switch (also localStorage
// ISAMPLES_FACET_TREE=0); `?facets=tree` / `=1` force on. The escape hatch lets us
// revert PER USER with no redeploy if the tree misbehaves; flipping the default back
// globally is a one-line change + redeploy.
FACET_TREE = (() => {
    const q = new URLSearchParams(location.search).get('facets');
    if (q === 'tree') return true;
    if (q === 'flat') return false;           // kill-switch
    const ls = (typeof localStorage !== 'undefined') ? localStorage.getItem('ISAMPLES_FACET_TREE') : null;
    if (ls === '0') return false;
    if (ls === '1') return true;
    return true;                              // DEFAULT ON
})()
// Hierarchical counts (one row per concept node: facet_type, concept_uri,
// parent_uri, depth, count) and per-sample membership (pid ↔ every ancestor).
facet_tree_url = `${R2_BASE}/isamples_202608_facet_tree_summaries.parquet`
membership_url = `${R2_BASE}/isamples_202608_sample_facet_membership.parquet`
// #290/#293 single-active-filter cross-filter cube over the trees + source.
// Precomputed COUNT(DISTINCT pid) for each target node given ONE active filter,
// so global-view cross-filtered tree counts are instant instead of a live
// membership near-full-scan. ~1k rows; same schema as facet_cross_filter.
tree_cross_filter_url = `${R2_BASE}/isamples_202608_facet_tree_cross_filter.parquet`
// #293 bitmask filter: per-pid tree-membership masks + the concept_uri→bit map.
// facetFilterSQL filters broad multi-tree selections with a columnar bitwise
// predicate over sample_facet_masks (~10 MB, one row/pid) instead of the
// 39M-row membership GROUP BY that stalls DuckDB-WASM. node_bits (~56 rows)
// maps each selected node to its bit. Best-effort: if either fails to load,
// facetFilterSQL falls back to the membership scan (no regression).
masks_url = `${R2_BASE}/isamples_202608_sample_facet_masks.parquet`
node_bits_url = `${R2_BASE}/isamples_202608_facet_node_bits.parquet`
// #304/#305 complete per-pid facet index: one row per LOCATED sample (incl. the
// ~29,917 with no tree membership that sample_facet_masks omits, #306) + source.
// The multi-filter global-view count path scans this with the node_bits bitmask
// predicate so 2+ active filters get correct counts instead of reverting to the
// unfiltered baseline (#304). Best-effort: if it isn't published/consistent,
// window.__facetIndexStatus stays 'pending' (then flips to 'failed') and the
// multi-filter path shows "Loading…"/"unavailable" (#313) rather than a
// misleading baseline (the honesty rule — never baseline under active
// filters).
index_url = `${R2_BASE}/isamples_202608_sample_facet_index.parquet`
// #313 P1: tiny trusted manifest (source, count, build_id, schema_version,
// total_rows) built DIRECTLY from samp_geo at build time — NOT read back from
// index_url — and independently validated against the real on-disk index by
// validate_frontend_derived.py. facetIndexReady reads THIS (a few KB) instead
// of scanning the 9.68 MB index_url on every page load; index_url itself is
// now touched only lazily, when a user's multi-filter count query actually
// runs. Always deployed paired with index_url (same build_id).
index_meta_url = `${R2_BASE}/isamples_202608_sample_facet_index_meta.parquet`

// Single source of truth for the search-index location (#334 round-1 review):
// the runtime substrate path and the manifest check MUST share this cell, so a
// version bump can't diverge them silently.
search_index_base = `${R2_BASE}/isamples_202608_search_index_v1`

// === #334 v0-detect: release-manifest boot cross-check ===
// The release manifest (isamples_202608_release_manifest.json, committed in
// this repo and deployed with the site; generated by
// tools/build_release_manifest.py; human twin: CANONICAL.md) enumerates the
// canonical data objects for this release. This cell cross-checks every URL
// the page pins against that list and complains LOUDLY on divergence —
// converting the #326 failure class ("sibling data files silently diverged
// for weeks") into "caught at next boot". v0 = detect only; deriving URLs
// FROM the manifest is the post-grant v1 (see #334).
// Non-blocking by design: runs after boot-critical cells (depends only on the
// URL cells), never throws, and a missing manifest is a console warning, not
// a user-facing failure.
manifestCheck = {
  const pinned = [
    h3_res4_url, h3_res6_url, h3_res8_url, lite_url, wide_url, facets_url,
    facet_summaries_url, cross_filter_url, vocab_labels_url, facet_tree_url,
    membership_url, tree_cross_filter_url, masks_url, node_bits_url,
    index_url, index_meta_url,
    // Runtime search-index loads, via the SHARED base cell (df.parquet is
    // offline-only per SEARCH_INDEX_V1.md and deliberately not pinned here):
    `${search_index_base}/build_stats.json`,
    `${search_index_base}/hot_tokens.json`,
    `${search_index_base}/shard_sizes.json`,
    `${search_index_base}/hot_topk.parquet`,
  ];
  // Hard-coded <link rel=preload> hrefs in the page header are a separate
  // divergence surface (round-1 P2): audit whatever is actually in the DOM.
  for (const l of document.querySelectorAll('link[rel="preload"][as="fetch"]')) {
    if (l.href && l.href.includes('data.isamples.org')) pinned.push(l.href);
  }
  const prefix = `${R2_BASE}/`;
  const pinnedNames = [...new Set(pinned.map(u => {
    if (u.startsWith(prefix)) return u.slice(prefix.length);
    const m = u.match(/data\.isamples\.org\/(.+)$/);
    return m ? m[1] : u;
  }))];
  const result = { status: 'unchecked', missing: [], extra: [], release_id: null };
  try {
    const resp = await fetch(new URL('isamples_202608_release_manifest.json', document.baseURI));
    if (!resp.ok) {
      console.warn(`#334 manifest check: manifest fetch HTTP ${resp.status} — skipping`);
      result.status = 'manifest-unavailable';
    } else {
      const manifest = await resp.json();
      result.release_id = manifest.release_id;
      const manifestNames = new Set(Object.keys(manifest.files || {}));
      // The search-index PATH must also agree (a SUBSTRATE_BASE _v1 -> _v2 bump
      // with a stale manifest must trip the check, not slide by).
      const mPath = ((manifest.search_index || {}).path || '').replace(/\/$/, '');
      const localPath = search_index_base.startsWith(prefix)
        ? search_index_base.slice(prefix.length) : search_index_base;
      if (mPath && mPath !== localPath) result.missing.push(`search_index path: page=${localPath} manifest=${mPath}`);
      result.missing = result.missing.concat(pinnedNames.filter(n => !manifestNames.has(n)));
      result.extra = [...manifestNames].filter(n => !pinnedNames.includes(n));
      result.status = result.missing.length ? 'MISMATCH' : 'ok';
      // Idempotency (round-1 P2): re-evaluations must not stack banners, and a
      // clean re-run must clear a stale one.
      document.getElementById('manifestMismatchBanner')?.remove();
      if (result.missing.length) {
        console.error('#334 RELEASE-MANIFEST MISMATCH — the page pins data files '
          + 'absent from the release manifest (stale manifest, or an unvetted '
          + 'suffix bump — see CANONICAL.md policy):', result.missing);
        const banner = document.createElement('div');
        banner.id = 'manifestMismatchBanner';
        banner.style.cssText = 'position:sticky;top:0;z-index:9999;background:#8a6d00;'
          + 'color:#fff;padding:6px 12px;font:13px sans-serif;cursor:pointer;';
        banner.textContent = 'Data release could not be validated — some data files '
          + 'are not in the release manifest. Results may be inconsistent. '
          + '(Details in the browser console; click to dismiss.)';
        banner.onclick = () => banner.remove();
        document.body.prepend(banner);
      } else if (result.extra.length) {
        // Informational only: the manifest may legitimately list objects this
        // page doesn't load (e.g. future additions). Not a divergence signal.
        console.info('#334 manifest check ok; manifest lists unpinned entries:', result.extra);
      } else {
        console.info(`#334 manifest check ok — ${pinnedNames.length} pinned URLs `
          + `all present in release ${manifest.release_id}`);
      }
    }
  } catch (e) {
    console.warn('#334 manifest check failed (non-fatal):', e);
    result.status = 'check-error';
  }
  if (typeof window !== 'undefined') window.__manifestCheck = result;
  return result;
}

// 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

// === Pure logic extracted to ES modules (issue #249, PR3) ===
// Same path-relative dynamic-import pattern as the palette above, so these
// resolve under both the custom domain (isamples.org) and fork project-pages
// previews. The functions are closure-free (no viewer/db/DOM) and unit-tested
// under Node (tests/unit/). Each `name = _module.fn` line is a single OJS cell
// that REPLACES the former inline `function name(){...}` cell.
_sqlBuilders = await import(new URL('assets/js/sql-builders.js', document.baseURI).href)
escSql = _sqlBuilders.escSql
escapeIlikePattern = _sqlBuilders.escapeIlikePattern
textSearchWhere = _sqlBuilders.textSearchWhere
textSearchScore = _sqlBuilders.textSearchScore
canonicalizePid = _sqlBuilders.canonicalizePid
looksLikePid = _sqlBuilders.looksLikePid
pidSearchWhere = _sqlBuilders.pidSearchWhere

_explorerUtils = await import(new URL('assets/js/explorer-utils.js', document.baseURI).href)
escapeHtml = _explorerUtils.escapeHtml
facetCountsDisplayState = _explorerUtils.facetCountsDisplayState
searchTerms = _explorerUtils.searchTerms
parseNum = _explorerUtils.parseNum
csvParamValues = _explorerUtils.csvParamValues
sourceUrl = _explorerUtils.sourceUrl
readHash = _explorerUtils.readHash
formatPlaceName = _explorerUtils.formatPlaceName
panelWriteAllowed = _explorerUtils.panelWriteAllowed

// === 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 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'));
    // #291: restored ?material=/?context=/?object_type= URIs are minimal nodes —
    // fill in each tree's inherited descendants + indeterminate ancestors.
    for (const key of TREE_DIM_KEYS) syncTreeVisual(TREE_DIM_BODY[key]);
}


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]) => {
        // #291: serialize the MINIMAL tree selection (parent URIs, not expanded
        // descendants) for any tree dim; treeSelection falls back to all checked
        // values when the dim is flat. Keeps shared links compact + stable.
        const values = treeSelection(key);
        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);
    }
}

// === 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;
}

// #281/#282/#291: the MINIMAL selection for tree dim `key` — the top-most checked
// tree nodes (a checked node whose ancestor is also checked is redundant, since the
// parent's subtree already covers it). This is the canonical selection used for filtering
// and URL serialization in tree mode; flat mode falls back to all checked values.
// #281/#282: the SINGLE source of truth for "Material is actually in tree mode" —
// the flag is on AND the tree rendered (renderMaterialTreeFacet falls back to the
// flat list if the hierarchy files fail to load). Every material code path keys off
// this, so a degraded flat fallback behaves fully flat — selection, filtering, AND
// cross-filter counts (Codex r2). Without it, filtering would query the missing
// membership file and counts would wrongly exclude material.
// #281/#282/#291: the hierarchical facet dims and their sidebar containers.
// facet_tree_summaries.facet_type / membership.facet_type use these same keys.
// `source` has no vocab tree → not here (stays a flat list).
TREE_DIM_BODY = ({ material: 'materialFilterBody', context: 'contextFilterBody', object_type: 'objectTypeFilterBody' })
TREE_DIM_KEYS = Object.keys(TREE_DIM_BODY)

// SINGLE source of truth for "dim `key` is actually in tree mode": the flag is on
// AND a tree rendered (renderTreeFacet falls back to the flat list if the hierarchy
// data fails to load). Every per-dim code path keys off this, so a degraded flat
// fallback behaves fully flat — selection, filtering, AND cross-filter counts.
function treeActive(key) {
    const body = TREE_DIM_BODY[key];
    return FACET_TREE && !!body && !!document.querySelector(`#${body} .facet-treenode`);
}

// Minimal (top-most checked) tree-node selection for dim `key` — a checked node
// whose ancestor is also checked is redundant (the parent's subtree covers it).
// Flat fallback to all checked values when the dim isn't in tree mode.
function treeSelection(key) {
    const bodyId = TREE_DIM_BODY[key];
    const body = bodyId ? document.getElementById(bodyId) : null;
    if (!treeActive(key) || !body) return getCheckedValues(bodyId);
    const out = [];
    body.querySelectorAll('.facet-treenode > .facet-treelabel input[type="checkbox"]:checked').forEach(cb => {
        const node = cb.closest('.facet-treenode');
        let anc = node && node.parentElement ? node.parentElement.closest('.facet-treenode') : null;
        let covered = false;
        while (anc) {
            const a = anc.querySelector(':scope > .facet-treelabel input[type="checkbox"]');
            if (a && a.checked && !a.disabled) { covered = true; break; }  // explicit ancestor covers it
            anc = anc.parentElement ? anc.parentElement.closest('.facet-treenode') : null;
        }
        if (!covered) out.push(cb.value);
    });
    return out;
}

// #281/#282: keep a tree body's visual state coherent after any change or URL
// restore: a checked parent fills in its descendants (checked+disabled = "included
// because the parent is"); unchecking a parent reverts them; a node with checked
// descendants but unchecked itself shows the indeterminate "–". Filtering reads
// treeSelection() (top-most) so inherited descendant checks never double-count.
function syncTreeVisual(bodyId) {
    const body = document.getElementById(bodyId);
    if (!FACET_TREE || !body || !body.querySelector('.facet-treenode')) return;
    const cbOf = (node) => node.querySelector(':scope > .facet-treelabel input[type="checkbox"]');
    const nodes = [...body.querySelectorAll('.facet-treenode')];  // DOM order = parents before children
    // Pass 1 (top-down): inherit checked state from an explicitly-checked ancestor.
    for (const node of nodes) {
        const cb = cbOf(node);
        if (!cb) continue;
        let anc = node.parentElement ? node.parentElement.closest('.facet-treenode') : null;
        let coveredByAnc = false;
        while (anc) {
            const a = cbOf(anc);
            if (a && a.checked && !a.disabled) { coveredByAnc = true; break; }
            anc = anc.parentElement ? anc.parentElement.closest('.facet-treenode') : null;
        }
        if (coveredByAnc) { cb.checked = true; cb.disabled = true; cb.indeterminate = false; }
        else if (cb.disabled) { cb.disabled = false; cb.checked = false; }  // was inherited, parent now off → revert
    }
    // Pass 2: indeterminate when not selected itself but a descendant is checked.
    for (const node of nodes) {
        const cb = cbOf(node);
        if (!cb) continue;
        cb.indeterminate = (!cb.checked) && !!node.querySelector(':scope > .facet-children input[type="checkbox"]:checked');
    }
}

// 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;
    // #300: once filtered clusters are ready, cluster mode IS filter-aware (the
    // h3 layer is aggregated off the filtered set), so the "filter only takes
    // effect at neighborhood zoom" apology is false — hide it, same as the
    // heatmap conjunct above.
    const filteredClustersOk = (typeof window !== 'undefined') && window.__filteredClustersReady === true;
    el.style.display = (active && inCluster && !heatOn && !filteredClustersOk) ? 'block' : 'none';
}

// 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.
// #293: build one "(<dim>_mask & <selected>) <> 0" predicate per active tree dim
// from the concept_uri→bit map (window.__nodeBits). The mask is a BigInt OR of the
// selected nodes' bits; sample_facet_masks already encodes the ancestor closure, so
// selecting a parent matches its whole subtree. Returns [] (→ caller uses the
// membership fallback) if the bit map isn't loaded, a selected node has no known
// bit, or a dim's mask is empty — never silently under-filter.
function treeMaskClauses(activeTree) {
    const bits = (typeof window !== 'undefined') ? window.__nodeBits : null;
    if (!bits) return [];
    const out = [];
    for (const { key, sel } of activeTree) {
        const dimBits = bits[key];
        if (!dimBits) return [];
        let mask = 0n;
        for (const uri of sel) {
            const idx = dimBits.get(uri);
            if (idx === undefined) return [];          // unknown node → fall back
            mask |= (1n << BigInt(idx));
        }
        if (mask === 0n) return [];                    // empty → avoid matching nothing
        out.push(`(${key}_mask & ${mask}) <> 0`);      // BigInt → decimal BIGINT literal
    }
    return out;
}

function facetFilterSQL() {
    // Each entry is a standalone `pid IN (...)` predicate; multiple are AND-ed.
    const parts = [];
    const facetsConds = [];
    // #281/#282/#291: for each hierarchical dim, a tree selection is a set of
    // concept NODES → filter via the membership table (which encodes each sample
    // under every ancestor), so a selected parent matches its whole subtree (no
    // client-side descendant expansion). A flat (non-tree) dim filters on facets_v3.
    const treeClauses = [];   // one "(facet_type='X' AND concept_uri IN(...))" per tree dim
    const activeTree = [];    // [{key, sel}] for tree-active dims (for the bitmask path)
    for (const key of TREE_DIM_KEYS) {
        const sel = treeSelection(key);
        if (sel.length === 0) continue;
        const list = sel.map(s => `'${escSql(s)}'`).join(',');
        if (treeActive(key)) {
            treeClauses.push(`(facet_type='${key}' AND concept_uri IN (${list}))`);
            activeTree.push({ key, sel });
        } else {
            facetsConds.push(`${key} IN (${list})`);
        }
    }
    // #293: prefer the bitmask predicate over sample_facet_masks — a single
    // columnar scan with no GROUP BY — which is set-identical to the membership
    // form but avoids the 39M-row scan that stalls DuckDB-WASM on broad multi-tree
    // selections. Fall back to the collapsed membership scan when the bit map
    // isn't available or a selected node has no bit (treeMaskClauses → []), so
    // results are always correct even before the mask artifacts are published.
    if (activeTree.length > 0) {
        const maskClauses = treeMaskClauses(activeTree);
        if (maskClauses.length === activeTree.length) {
            parts.push(`pid IN (SELECT pid FROM read_parquet('${masks_url}') WHERE ${maskClauses.join(' AND ')})`);
        } else {
            // Fallback: collapse the tree-dim selections into ONE membership scan
            // (OR within, HAVING COUNT(DISTINCT facet_type)=N across).
            parts.push(`pid IN (SELECT pid FROM read_parquet('${membership_url}') WHERE ${treeClauses.join(' OR ')} GROUP BY pid HAVING COUNT(DISTINCT facet_type) = ${treeClauses.length})`);
        }
    }
    if (facetsConds.length > 0) {
        parts.push(`pid IN (SELECT DISTINCT pid FROM read_parquet('${facets_url}') WHERE ${facetsConds.join(' AND ')})`);
    }
    if (parts.length === 0) return '';
    return ' AND ' + parts.map(p => `(${p})`).join(' AND ');
}

// #300: true when a facet filter is active AND lite carries h3_res4/res6, so the
// cluster layer should be aggregated from the FILTERED sample set instead of the
// pre-aggregated (facet-blind) summary parquets. Top-level so both phase1 and the
// zoom watcher's loadRes can use it.
function wantFilteredClusters() {
    return hasFacetFilters() && (typeof window !== 'undefined' && window.__filteredClustersReady === true);
}

// #300: a STABLE, SEMANTIC description of what the current cluster layer should
// contain — data kind (filtered vs pre-aggregated summary), the active ?sources=
// set, and the tree facet selections. Captured BEFORE a cluster load and compared
// again AFTER the await so a filter change mid-query can't mislabel the cache
// (Codex P0.2/P1.3). Deliberately NOT the SQL text: masks becoming ready can
// change the SQL strategy without changing results.
function clusterSig(kind) {
    return JSON.stringify({
        kind,   // 'filtered' | 'summary' — explicit so a caller can label what it
                // ACTUALLY loaded, not what the live state currently wants
        sources: getActiveSources().slice().sort(),
        material: treeSelection('material').slice().sort(),
        context: treeSelection('context').slice().sort(),
        objectType: treeSelection('object_type').slice().sort(),
    });
}
// The signature for what the cluster layer SHOULD contain right now.
function desiredClusterSig() {
    return clusterSig(wantFilteredClusters() ? 'filtered' : 'summary');
}

// #300: the filtered-cluster aggregation off samples_map_lite (masks-backed via
// facetFilterSQL). Same columns + grain + INTEGER casts as the pre-aggregated h3
// summary parquet (build_h3_summary), so the loadRes render/cache/stats path is
// unchanged. dominant_source is recomputed over the FILTERED subset (source-
// filtered at the row level), the coherent meaning when a filter is active.
function filteredClusterSQL(res) {
    return `
        WITH base AS (
            SELECT h3_res${res} AS cell, source, latitude, longitude
            FROM read_parquet('${lite_url}')
            WHERE h3_res${res} IS NOT NULL${sourceFilterSQL('source')}${facetFilterSQL()}
        ),
        sc AS (SELECT cell, source, COUNT(*) AS c FROM base GROUP BY cell, source),
        dom AS (SELECT cell, source AS dominant_source,
                ROW_NUMBER() OVER (PARTITION BY cell ORDER BY c DESC, source ASC) AS rn FROM sc),
        agg AS (SELECT cell, COUNT(*)::INTEGER AS sample_count,
                ROUND(AVG(latitude), 6) AS center_lat, ROUND(AVG(longitude), 6) AS center_lng,
                COUNT(DISTINCT source)::INTEGER AS source_count
                FROM base GROUP BY cell)
        SELECT CAST(agg.cell AS VARCHAR) AS h3_cell_dec, agg.sample_count,
               agg.center_lat, agg.center_lng, dom.dominant_source, agg.source_count
        FROM agg JOIN dom ON dom.cell = agg.cell AND dom.rn = 1
    `;
}

// 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.
// - loadViewportSamples() (#220): point-mode sample loader + "Samples in View"
//   count, so point mode uses the same wrap-aware bbox as the table.
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');
        el.classList.remove('count-unavailable');   // #304/#305: real count clears the dash
        el.removeAttribute('title');

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

// Coherence audit (2026-08-04), structural finding: the honesty rule was
// call-site discipline, not an invariant. #340's whole mechanism was that
// "in flight" was conveyed by OPACITY ALONE — this function adds a class and
// leaves the old numeric text intact — so a recompute that never settled left
// confident, precise, wrong numbers on screen forever with no signal.
//
// Fix: after a short grace period, an unsettled count stops asserting a number
// and says "(Loading…)" instead. The grace period matters — this fires on every
// camera moveStart, and swapping text immediately would make counts flicker on
// every small pan.
//
// Be clear about what 400 ms does and does not buy (Codex review): the timer
// starts at moveStart, but the actual work waits for moveEnd plus the 250 ms
// refreshFacetCounts debounce. So on an animated flight longer than ~150 ms,
// "(Loading…)" appears BEFORE the query even starts, and a one-second pan shows
// it for most of the flight. That is honest — the counts really are unknown
// mid-flight — but it is emphatically not limited to pathological stalls. The
// window only suppresses the flicker on short, snappy interactions.
//
// This is deliberately NOT a watchdog that forces a terminal state: per the
// audit's structural recommendation, honesty only requires that invalid data
// stop LOOKING current. A persistent "(Loading…)" is honest. Making the work
// actually terminate (and cancelling the underlying DuckDB query) is separate,
// larger, post-grant work.
// NB: state lives on `window`, not a top-level `let`. Quarto {ojs} cells reject
// top-level const/let/var — each top-level statement is a reactive cell, and a
// bad declaration cascades and breaks every dependent cell (i.e. the whole
// Explorer). `window.__*` is the established pattern in this file for mutable
// cross-cell state (cf. window.__searchFilter, window.__facetIndexStatus).
function facetCountsStaleDelayMs() { return 400; }

function clearFacetCountsStaleTimer() {
    if (typeof window === 'undefined') return;
    if (window.__facetCountsStaleTimer) {
        clearTimeout(window.__facetCountsStaleTimer);
        window.__facetCountsStaleTimer = null;
    }
}

function markFacetCountsRecomputing() {
    document.querySelectorAll('.facet-count').forEach(el => el.classList.add('recomputing'));
    clearFacetCountsStaleTimer();
    window.__facetCountsStaleTimer = setTimeout(() => {
        window.__facetCountsStaleTimer = null;
        // Self-filtering: applyFacetCounts removes `.recomputing` as each dim
        // settles, so anything still carrying it is genuinely unresolved. No
        // per-dimension bookkeeping needed, and a partially-settled repaint
        // cannot be clobbered.
        const inFlight = Array.from(document.querySelectorAll('.facet-count.recomputing'));
        if (!inFlight.length) return;
        const dims = new Set();
        for (const el of inFlight) {
            // Never overwrite the honest dash (e.g. counts unavailable under an
            // active search, #340) with a "still loading" claim — that would be
            // a downgrade from "we can't know this" to "we're about to know it".
            if (el.classList.contains('count-unavailable')) continue;
            el.textContent = '(Loading…)';
            el.removeAttribute('title');
            const k = el.getAttribute('data-facet');
            if (k) dims.add(k);
        }
        // Unknown must not imply zero: drop stale `.zero` dimming on exactly
        // the dims we just marked unknown, and no others.
        for (const k of dims) clearStaleZeroRows(k);
    }, facetCountsStaleDelayMs());
}

// #304/#305: the honesty rule — when active filters are in play but we cannot
// compute correct cross-filtered counts (the complete index is unpublished /
// inconsistent, or a count query failed), we must NOT fall back to the unfiltered
// baseline (that misleading baseline IS the #304 bug). Show an explicit
// "unavailable" dash instead. Scoped to the given dim keys (default: all).
function markFacetCountsUnavailable(facetKeys = null) {
    // Terminal state: cancel any pending stale-swap so it can't run and
    // (harmlessly, but confusingly) re-touch elements after we've settled.
    if (facetKeys === null) clearFacetCountsStaleTimer();
    const keys = facetKeys || ['source', 'material', 'context', 'object_type'];
    for (const key of keys) {
        document.querySelectorAll(`.facet-count[data-facet="${key}"]`).forEach(el => {
            el.textContent = '(—)';
            el.classList.remove('recomputing');
            el.classList.add('count-unavailable');
            el.title = 'Count unavailable for this filter combination';
        });
        clearStaleZeroRows(key);
    }
}

// #340: `.zero` is set by applyFacetCounts from a PREVIOUS, authoritative
// count. Once a count becomes unknown (unavailable OR still loading), leaving
// the row greyed-out as "0" asserts a number we just admitted we don't have —
// the same misleading-number problem in a different costume. A later real
// count restores the correct state via applyFacetCounts' classList.toggle.
function clearStaleZeroRows(facetKey) {
    document.querySelectorAll(`.facet-row[data-facet="${facetKey}"].zero`).forEach(row => {
        row.classList.remove('zero');
    });
}

// #313 P0: the facet index (sample_facet_index) is still loading — distinct
// from markFacetCountsUnavailable's "this session genuinely can't compute it"
// dash. On a slow connection the cold-boot preflight can take ~20-80s; until
// window.__facetIndexStatus settles to 'ready' or 'failed' the UI must say
// "still coming" rather than show a dash that looks just as permanent as a
// real failure. __onFacetIndexReady (wired below) reconciles real counts in
// once status flips to 'ready'. Scoped to the given dim keys (default: all).
function markFacetCountsPending(facetKeys = null) {
    // Already the "still loading" text the stale-swap would produce; drop the
    // timer so it doesn't fire redundantly.
    if (facetKeys === null) clearFacetCountsStaleTimer();
    const keys = facetKeys || ['source', 'material', 'context', 'object_type'];
    for (const key of keys) {
        document.querySelectorAll(`.facet-count[data-facet="${key}"]`).forEach(el => {
            el.textContent = '(Loading…)';
            el.classList.add('recomputing');           // same dimmed/italic treatment as in-flight counts
            el.classList.remove('count-unavailable');   // NOT the "—" dash — this is honest "still loading"
            el.removeAttribute('title');
        });
        clearStaleZeroRows(key);   // #340: same invariant — unknown never implies zero
    }
}

// === URL State: encode/decode globe state in hash fragment ===
// (decode side — parseNum + readHash — extracted to assets/js/explorer-utils.js, PR3)
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();
}

// === Single URL-hash writer (#208 smell 1a) ===
// The ONLY place that writes the globe hash. Centralizes the
// `_suppressHashWrite` gate that was previously repeated at the camera/
// moveEnd writers and silently omitted at the selection/share writers.
//   replace: true (default) → history.replaceState; false → pushState.
//   force:   true → write even when _suppressHashWrite is set. Used by the
//            explicit user-action writers (map/row selection, enter/exit
//            point mode, source-filter selection-invalidation, Share button)
//            that must always reflect the action; only the camera.changed /
//            moveEnd settled-camera writers honor the suppress gate (force
//            omitted). See REFACTOR_PR4_PLAN.md §1 for the per-site matrix.
function writeGlobeHash(v, { replace = true, force = false } = {}) {
    if (v._suppressHashWrite && !force) return;
    const hash = buildHash(v);
    if (replace) history.replaceState(null, '', hash);
    else history.pushState(null, '', hash);
}

// === 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 placeStr = formatPlaceName(sample.place_name);
    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;">${escapeHtml(placeStr)}</div>` : ''}
            ${sample.result_time ? `<div style="font-size: 11px; color: #888;">Date: ${escapeHtml(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 desc = formatPlaceName(s.place_name);
        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">${escapeHtml(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

// === 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');
    // #300: DuckDB-WASM (the non-threaded MVP build this page loads) DEADLOCKS
    // when the heavy filtered-cluster aggregation (filteredClusterSQL, reading
    // samples_map_lite + sample_facet_masks) runs CONCURRENTLY with boot's other
    // queries — yet the identical query completes in ~2.5s once the connection is
    // idle, and 2 concurrent post-boot queries are fine.
    //
    // We do NOT serialize all queries (that queued interactive search behind the
    // whole boot storm and blew the smoke gate's search budget). Instead we keep
    // queries concurrent (fast boot/search) and track in-flight count so the
    // filtered-cluster load alone can wait for the connection to go idle before
    // issuing (see whenConnectionIdle / loadRes). _inFlight is read there.
    const origQuery = instance.query.bind(instance);
    let inFlight = 0;
    instance.query = (...args) => {
        inFlight++;
        const p = origQuery(...args);
        p.then(() => {}, () => {}).finally(() => { inFlight--; });
        return p;
    };
    instance._inFlight = () => inFlight;
    return instance;
}

// #293: load the concept_uri→bit map once at startup so facetFilterSQL can turn
// a tree-node selection into a bitmask and filter sample_facet_masks with a cheap
// columnar predicate (instead of the 39M-row membership GROUP BY). Stashed on
// window for synchronous access from facetFilterSQL (same pattern as
// window.conceptLabelForUri). Best-effort: on ANY failure window.__nodeBits stays
// null and facetFilterSQL falls back to the membership scan — so this is safe to
// ship before sample_facet_masks / facet_node_bits are published.
// #313 P3: split off from the old single nodeBitsReady cell. This is JUST
// step 1 (node_bits) — the ONLY thing facetIndexReady actually needs
// (__nodeBitsMap/__nodeBitsBuild). Previously facetIndexReady depended on the
// WHOLE nodeBitsReady cell (`const _ = nodeBitsReady`), which — because OJS
// resolves a cell only when its async function body returns — meant
// facetIndexReady couldn't even START until the masks scan (step 2, 9.67 MB)
// had ALSO finished, even though the values it needs are published
// synchronously partway through, before step 2 begins. Splitting removes the
// masks scan from facetIndexReady's critical path entirely.
nodeBitsCoreReady = {
    window.__nodeBitsMap = null;
    window.__nodeBitsBuild = null;
    try {
        const rows = await db.query(
            `SELECT facet_type, concept_uri, bit_index, build_id FROM read_parquet('${node_bits_url}')`);
        const map = { material: new Map(), context: new Map(), object_type: new Map() };
        const nbBuilds = new Set();
        for (const r of rows) {
            if (map[r.facet_type]) map[r.facet_type].set(r.concept_uri, Number(r.bit_index));
            nbBuilds.add(r.build_id);
        }
        const haveBits = ['material', 'context', 'object_type'].every(k => map[k].size > 0);
        // node_bits must carry exactly ONE build_id (a mixed file is corrupt; don't
        // let a last-row-wins value coincidentally match masks — Codex r2).
        if (!haveBits || nbBuilds.size !== 1) return false;
        // node_bits is valid on its own → publish the bit map + generation NOW so the
        // count path (which depends only on node_bits + the index) runs even if masks
        // is absent. facetIndexReady consumes window.__nodeBitsBuild.
        window.__nodeBitsMap = map;
        window.__nodeBitsBuild = [...nbBuilds][0];
        return true;
    } catch (err) {
        console.warn('node_bits preflight failed; facetFilterSQL + count path use fallbacks:', err);
        window.__nodeBitsMap = null;
        window.__nodeBitsBuild = null;
        return false;
    }
}

// Two SEPARATE readiness signals (Codex P2 #4 — they were wrongly coupled):
//   __nodeBitsMap + __nodeBitsBuild (nodeBitsCoreReady, above) → the concept_uri→
//       bit map + its generation. The #304/#305 COUNT path (sample_facet_index)
//       needs ONLY this, not masks.
//   __nodeBits → the SAME map, but advertised only after the masks file
//       preflights & generation-matches. facetFilterSQL's mask FILTER path reads
//       masks_url, so it must not run until masks is proven present/consistent.
// A missing/mismatched masks file must NOT disable the (valid) count bundle.
nodeBitsReady = {
    window.__nodeBits = null;
    const coreOk = await nodeBitsCoreReady;
    if (!coreOk) return false;
    // #313 P3: let facetIndexReady's (now cheap, meta-file-based) preflight
    // settle FIRST — ready or failed, either is fine, we just wait for it to
    // finish — before starting this 9.67 MB masks scan. Same single-connection-
    // contention discipline as whenConnectionIdle elsewhere in this file:
    // running the masks scan concurrently with facetIndexReady's queries would
    // let a slow masks fetch delay the (now supposed to be near-instant)
    // count-readiness gate, defeating the point of this split.
    try { await facetIndexReady; } catch (err) { /* facetIndexReady reports its own failure */ }
    const map = window.__nodeBitsMap;
    const nbBuild = window.__nodeBitsBuild;
    try {
        const mrows = await db.query(
            `SELECT DISTINCT build_id FROM read_parquet('${masks_url}')`);
        const maskBuilds = mrows.map(r => r.build_id);
        if (maskBuilds.length !== 1 || maskBuilds[0] !== nbBuild) {
            console.warn('masks/node_bits build_id mismatch; using membership fallback (count path unaffected)',
                         { nbBuild, maskBuilds });
            return false;
        }
        window.__nodeBits = map;
        return true;
    } catch (err) {
        console.warn('masks preflight failed; facetFilterSQL uses membership fallback (count path unaffected):', err);
        return false;
    }
}

// #304/#305: preflight the complete per-pid facet index (sample_facet_index). The
// multi-filter global-view count path scans it; it must be (a) present/readable,
// (b) schema_version we understand, (c) from the SAME node_bits generation as the
// bit map (build_id membership half == window.__nodeBitsBuild) so the mask bits
// mean what we think, AND (d) COVERAGE-COMPLETE — its pid count equals the located
// universe (facets) so a stale/incomplete index (the #306 drift class, which a
// membership-only id is blind to) can't silently undercount. The full coverage
// fingerprint is enforced at BUILD time (validate_frontend_derived); this is the
// cheap runtime handshake the plan calls for (SERIALIZATIONS §4.12). Only then
// advertise readiness; otherwise the multi-filter path shows "Loading…" while
// this preflight is still in flight and "unavailable" once it's conclusively
// failed — never a baseline (honesty rule; #313 P0 — see facetCountsDisplayState
// in assets/js/explorer-utils.js for the pending-vs-failed UI decision).
// Depends on nodeBitsCoreReady (#313 P3) for __nodeBitsBuild — NOT the full
// nodeBitsReady, so this preflight never waits on the 9.67 MB masks scan.
facetIndexReady = {
    const _ = nodeBitsCoreReady;      // sequence after JUST the node_bits preflight
    // #313 P0: window.__facetIndexStatus replaces the old boolean
    // window.__facetIndexReady, which conflated "still loading" and "failed
    // to load" into a single false value — so on a slow connection the UI
    // showed the same permanent-looking dash for both during the entire
    // ~20-80s cold-boot window. Three states instead: 'pending' (this
    // preflight hasn't concluded yet — show "Loading…"), 'ready' (validated,
    // counts are trustworthy), 'failed' (a check below failed, or the query
    // threw — permanent for this session until refresh, matching the OLD
    // dash-forever behavior but ONLY for the genuine-failure case).
    window.__facetIndexStatus = 'pending';
    const fail = (...warnArgs) => {       // every preflight-failed exit goes through here
        if (warnArgs.length) console.warn(...warnArgs);
        window.__facetIndexStatus = 'failed';
        return false;
    };
    const INDEX_SCHEMA_VERSION = 1;   // mirrors build_frontend_derived.INDEX_SCHEMA_VERSION
    try {
        const nbBuild = window.__nodeBitsBuild;
        if (!nbBuild) return fail();   // no usable bit map → index path can't run
        // #313 P1: read the tiny trusted MANIFEST (index_meta_url, a few KB) instead
        // of scanning the 9.68 MB sample_facet_index.parquet directly. The manifest
        // is built at BUILD TIME straight from samp_geo (the same authoritative
        // located-universe table sample_facet_index itself derives from — NOT read
        // back from the index) and independently validated against a fresh full
        // scan of the real on-disk index by validate_frontend_derived.py (P1 gate).
        // So the checks below are IDENTICAL in intent to the old ones (schema
        // version, generation match, per-source coverage vs facet_summaries) —
        // only the data source changed, from a live 6M-row scan to a pre-verified
        // handful of rows. sample_facet_index.parquet itself is now read ONLY
        // lazily, when a user's actual multi-filter count query runs.
        const rows = await db.query(`SELECT * FROM read_parquet('${index_meta_url}')`);
        if (!rows || rows.length === 0) return fail('sample_facet_index_meta empty/missing; multi-filter counts unavailable');
        const svs = new Set(rows.map(r => Number(r.schema_version)));
        if (svs.size !== 1) {
            return fail('sample_facet_index_meta carries mixed schema_version; multi-filter counts unavailable', [...svs]);
        }
        const sv = [...svs][0];
        if (sv !== INDEX_SCHEMA_VERSION) {
            return fail('sample_facet_index_meta schema_version unsupported; multi-filter counts unavailable', sv);
        }
        const buildIds = new Set(rows.map(r => String(r.build_id)));
        if (buildIds.size !== 1) {
            return fail('sample_facet_index_meta carries mixed build_id; multi-filter counts unavailable', [...buildIds]);
        }
        const membershipHalf = [...buildIds][0].split(':', 1)[0];
        if (membershipHalf !== nbBuild) {
            return fail('sample_facet_index_meta/node_bits generation mismatch; multi-filter counts unavailable',
                         { indexMembershipHalf: membershipHalf, nbBuild });
        }
        // (d) runtime coverage handshake: the manifest's per-source histogram
        // (computed at build time from samp_geo, same as facet_summaries' source
        // rows, and independently cross-checked against the real index by the
        // validator) must agree with facet_summaries' source rows. Same symmetric-
        // diff comparison as before, over two tiny already-loaded files instead of
        // a live scan of the big index. See the old version of this cell (git
        // history) for the full rationale on why this specific check exists and
        // what it does/doesn't catch — unchanged by this refactor.
        const cov = await db.query(`
            WITH i AS (SELECT source AS v, count AS c FROM read_parquet('${index_meta_url}')),
                 f AS (SELECT facet_value AS v, count AS c
                       FROM read_parquet('${facet_summaries_url}') WHERE facet_type = 'source')
            SELECT (SELECT COUNT(*) FROM (SELECT * FROM i EXCEPT SELECT * FROM f))
                 + (SELECT COUNT(*) FROM (SELECT * FROM f EXCEPT SELECT * FROM i)) AS mismatch`);
        if (Number(cov[0].mismatch) !== 0) {
            return fail('sample_facet_index_meta per-source coverage != located universe; multi-filter counts unavailable',
                         { mismatch: Number(cov[0].mismatch) });
        }
        window.__facetIndexStatus = 'ready';
        // readiness can flip true AFTER boot already computed counts once (lost the
        // async race) — reconcile any active multi-filter now (Codex P1 boot race).
        if (typeof window.__onFacetIndexReady === 'function') window.__onFacetIndexReady();
        return true;
    } catch (err) {
        return fail('sample_facet_index_meta preflight failed; multi-filter global counts will show unavailable:', err);
    }
}

// #300: preflight whether samples_map_lite carries h3_res4/h3_res6. The explorer
// aggregates FILTERED clusters on the fly off lite (GROUP BY the res-appropriate
// h3 column + the #293 mask predicate) so a broad facet filter at world zoom
// renders as fast filtered clusters instead of capped raw points. The hard
// requirement is ONLY that lite has res4/res6 (masks readiness is orthogonal:
// facetFilterSQL() self-falls-back to the membership scan when masks absent —
// that affects speed, not correctness). Best-effort: on ANY failure the flag
// stays false and computeTargetMode keeps today's point-mode behavior, so this
// is safe to ship BEFORE the lite republish. When readiness flips true after a
// facet is already active, window.__onFilteredClustersReady (set by the zoom
// watcher) reconciles the globe.
filteredClustersReady = {
    window.__filteredClustersReady = false;
    try {
        await db.query(`SELECT h3_res4, h3_res6 FROM read_parquet('${lite_url}') LIMIT 1`);
        window.__filteredClustersReady = true;
        if (typeof window.__onFilteredClustersReady === 'function') window.__onFilteredClustersReady();
        return true;
    } catch (err) {
        console.warn('samples_map_lite lacks h3_res4/h3_res6; #300 filtered clusters disabled (point-mode fallback):', err);
        window.__filteredClustersReady = false;
        return 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 };
    // #172 Inc 1 — PANEL/LIST OWNERSHIP GENERATION (unified rule, Codex round-5):
    // ANY write to the rendered panel list (#samplesSection) — clear or replace,
    // synchronous or asynchronous — advances _panelGen. Async producers ALSO
    // capture it at start and may only write list+pins while still current (see
    // panelWriteAllowed). Synchronous clears just advance it: the bump's job is to
    // invalidate any in-flight async producer so a slow search/hydration can no
    // longer resurrect a panel the user has since replaced or cleared. The pid
    // deep-link is card-only (never writes the list) so it never bumps this —
    // that's why the boot search+pid list still renders.
    v._panelGen = 0;
    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

    // #172 pin-overlay Inc 1 (option C): search-result pin overlay. Added to
    // scene.primitives AFTER h3Points and samplePoints so it renders ABOVE both
    // (z-order rule). Always shown — the overlay is independent of the
    // cluster/point mode toggle.
    v.searchResultPoints = new Cesium.PointPrimitiveCollection();
    v.scene.primitives.add(v.searchResultPoints);

    // Test hook (#172, Codex round-1 P1.4 / P2): read-only snapshot of the pin
    // overlay — [{ pid, lat, lng }] — so specs can assert identity/position and
    // exact set equality, not just a count. Re-reads the collection on every
    // call via the current `v`; returns [] if the collection is missing so a
    // recreated viewer never leaves a stale closure raising.
    if (typeof window !== 'undefined') window.__searchPins = () => {
        const col = v.searchResultPoints;
        if (!col) return [];
        const out = [];
        for (let i = 0; i < col.length; i++) {
            const id = col.get(i).id || {};
            out.push({ pid: id.pid, lat: id.lat, lng: id.lng });
        }
        return out;
    };

    // Test hook (#172, Codex round-3/4 P2): faithfully replay a result-pin CLICK
    // by index — the FULL ceremony the on-globe LEFT_CLICK handler runs, INCLUDING
    // inMapCardAt (canvas centre) so the rich floating-card hydration path runs,
    // plus the shared selection helper and the pid hash push. Lets specs exercise
    // pin selection and Back-navigation without Cesium canvas picking (not feasible
    // in Playwright). Installed ONLY under WebDriver (Playwright sets
    // navigator.webdriver) so it can't be invoked in a normal session. Returns
    // false if there is no pin at that index.
    if (typeof window !== 'undefined' && typeof navigator !== 'undefined' && navigator.webdriver === true) {
        window.__clickSearchPin = (i = 0) => {
            const col = v.searchResultPoints;
            if (!col || i < 0 || i >= col.length) return false;
            const meta = col.get(i).id;
            const canvas = v.scene.canvas;
            const inMapCardAt = { x: canvas.clientWidth / 2, y: canvas.clientHeight / 2 };
            const isStale = freshSelectionToken(v);
            if (v.selectSearchResult) v.selectSearchResult(meta, { fly: true, inMapCardAt, isStale });
            writeGlobeHash(v, { replace: false, force: true });
            return true;
        };
    }

    // 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: "",
        }
    });
    // Cesium's documented default label background; restored for hovers that
    // carry no source (#172 P2 source-colored hover, below).
    const LABEL_BG_DEFAULT = new Cesium.Color(0.165, 0.165, 0.165, 0.8);

    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;
            // #172 P2 (Codex round-1): source-colored hover background for both
            // sample points AND search-result pins, per the option (C) contract
            // ("source badge color"). Cluster/plain hovers keep the default.
            let hoverSource = null;
            if (typeof meta === 'object' && (meta.type === 'sample' || meta.type === 'searchResult')) {
                v.pointLabel.label.text = `${meta.label || meta.pid}`;
                hoverSource = meta.source;
            } else if (typeof meta === 'object' && meta.count) {
                v.pointLabel.label.text = `${meta.source}: ${meta.count.toLocaleString()} samples`;
            } else {
                v.pointLabel.label.text = String(meta);
            }
            v.pointLabel.label.backgroundColor = (hoverSource && SOURCE_COLORS[hoverSource])
                ? Cesium.Color.fromCssColorString(SOURCE_COLORS[hoverSource]).withAlpha(0.85)
                : LABEL_BG_DEFAULT;
        } 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 === 'searchResult') {
            // --- Search-result pin click (#172 pin-overlay Inc 1, option C) ---
            // Runs the same selection ceremony as a sample click (card,
            // selection state, flight, full in-map detail) via the shared
            // helper, but PRESERVES the #samplesSection search-results list the
            // user is browsing. Reuse the freshness token already bumped above
            // (isStale) so the helper does not double-bump (Codex round-1 P1.3).
            if (v.selectSearchResult) {
                v.selectSearchResult(meta, { fly: true, inMapCardAt: { x: e.position.x, y: e.position.y }, isStale });
            }
            writeGlobeHash(v, { replace: false, force: true });

        } else 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;
            writeGlobeHash(v, { replace: false, force: true });
            // Clear nearby list
            const sampEl = document.getElementById('samplesSection');
            if (sampEl) sampEl.innerHTML = '';
            // #172 Inc 1 (Codex round-1 P1.2 / round-5 unified rule): this click
            // tears down the rendered results list, so the pin overlay (its
            // snapshot) goes with it AND _panelGen advances — a slow in-flight
            // search that captured an earlier gen now bails instead of
            // resurrecting the list the user just replaced with this selection.
            if (v.searchResultPoints) v.searchResultPoints.removeAll();
            v._panelGen++;

            // 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 ---
            // #172 Inc 1 (Codex round-4 P1): claim panel ownership — this cluster
            // click is a new list producer, so an older in-flight search render
            // (which checks its own captured gen) bails instead of overwriting
            // these nearby rows.
            const myPanelGen = ++v._panelGen;
            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;
            writeGlobeHash(v, { replace: false, force: true });

            const sampEl = document.getElementById('samplesSection');
            if (sampEl) sampEl.innerHTML = '<div style="text-align: center; color: #999; padding: 12px;">Loading nearby samples...</div>';
            // #172 Inc 1 (Codex round-1 P1.2, snapshot semantics): a cluster
            // click replaces the results list with nearby samples, so the
            // result-pin overlay (its snapshot) is cleared too.
            if (v.searchResultPoints) v.searchResultPoints.removeAll();

            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;
                // #172 Inc 1 (Codex round-4 P1): only write if this click still
                // owns the panel. Closes the reverse race — a search that
                // STARTED earlier but resolves later has a stale panel gen and
                // must not overwrite these rows. (round-3 P1): write list + pins
                // as ONE owned operation — no await between this guard, the
                // re-clear, and updateSamples, so nothing can interpose.
                if (!panelWriteAllowed(myPanelGen, v._panelGen)) return;
                if (v.searchResultPoints) v.searchResultPoints.removeAll();
                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;
}

// === 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 };
    // #300: phase1 ALWAYS loads the pre-aggregated summary (facet-blind) clusters,
    // so label the cache 'summary' explicitly — desiredClusterSig() could say
    // 'filtered' if readiness + facet hydration already resolved, which would let
    // the boot/readiness reconcile mistake this facet-blind layer for filtered
    // data (Codex round-2 P1.3). Without this seed the first reconcile couldn't
    // tell whether the initial layer matched the desired filter state.
    viewer._clusterFilterSig = clusterSig('summary');

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

// === Load facet summaries + SKOS prefLabels, populate filter checkboxes ===
//
// Checkbox value = full URI (matches the URI strings stored in
// sample_facets_v4.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('');
        };

        // #281/#282: render Material as an expandable tree when the preview flag
        // is on; flat list otherwise. context/object_type/source stay flat.
        // Defined inline so it closes over prettyLabel / escapers / grouped / db.
        // #291: render any hierarchical dim (material/context/object_type) as a tree
        // from facet_tree_summaries; fall back to the flat list on load failure.
        async function renderTreeFacet(facetType, bodyId, flatItems, allLabel) {
            const body = document.getElementById(bodyId);
            if (!body) return;
            let rows;
            try {
                rows = await db.query(`SELECT concept_uri, parent_uri, depth, count FROM read_parquet('${facet_tree_url}') WHERE facet_type='${facetType}'`);
            } catch (err) {
                console.warn(`facet_tree load failed for ${facetType}; flat fallback:`, err);
                renderFilter(bodyId, facetType, flatItems);
                return;
            }
            if (!rows || rows.length === 0) { renderFilter(bodyId, facetType, flatItems); return; }
            const nodes = new Map();
            for (const r of rows) nodes.set(r.concept_uri, { uri: r.concept_uri, parent: r.parent_uri, depth: Number(r.depth), count: Number(r.count), label: prettyLabel(r.concept_uri), kids: [] });
            let root = null;
            for (const n of nodes.values()) { if (n.parent == null) root = n; else if (nodes.has(n.parent)) nodes.get(n.parent).kids.push(n); }
            for (const n of nodes.values()) n.kids.sort((a, b) => a.label.localeCompare(b.label));  // #282 alphabetical within level
            // Baseline counts come from the tree (Codex), not the flat summaries.
            viewer._baselineCounts[facetType] = new Map([...nodes.values()].map(n => [n.uri, n.count]));
            // First two levels unfolded (#281): depth 1 + 2 visible; depth ≥3 collapsed.
            const nodeHtml = (n) => {
                const hasKids = n.kids.length > 0;
                const open = hasKids && n.depth < 2;
                const caret = hasKids
                    ? `<span class="facet-caret" role="button" aria-label="expand or collapse">${open ? '▾' : '▸'}</span>`
                    : `<span class="facet-caret-spacer"></span>`;
                return `<div class="facet-treenode" data-depth="${n.depth}">`
                    + caret
                    + `<label class="facet-row facet-treelabel" data-facet="${facetType}" data-value="${escAttr(n.uri)}" title="${escAttr(n.uri)}">`
                    + `<input type="checkbox" value="${escAttr(n.uri)}"> ${escText(n.label)} `
                    + `<span class="facet-count" data-facet="${facetType}" data-value="${escAttr(n.uri)}" style="color:#999">(${n.count.toLocaleString()})</span>`
                    + `</label>`
                    + (hasKids ? `<div class="facet-children${open ? '' : ' collapsed'}">` + n.kids.map(nodeHtml).join('') + `</div>` : '')
                    + `</div>`;
            };
            // Root renders as a non-selectable "All …" grouping label (selecting it = no filter).
            body.innerHTML =
                `<div class="facet-treeroot">${escText(root ? root.label : allLabel)}`
                + (root ? ` <span class="facet-count" data-facet="${facetType}" data-value="${escAttr(root.uri)}" style="color:#999">(${root.count.toLocaleString()})</span>` : '')
                + `</div>`
                + (root ? root.kids.map(nodeHtml).join('') : '');
            body.querySelectorAll('.facet-caret').forEach(c => c.addEventListener('click', (e) => {
                e.preventDefault(); e.stopPropagation();
                const node = c.closest('.facet-treenode');
                const kids = node && node.querySelector(':scope > .facet-children');
                if (kids) { const collapsed = kids.classList.toggle('collapsed'); c.textContent = collapsed ? '▸' : '▾'; }
            }));
            // Tri-state + inherited-check visual sync on any checkbox toggle. Filtering
            // reads treeSelection() (top-most) so inherited checks don't double-count.
            body.addEventListener('change', () => syncTreeVisual(bodyId));
            syncTreeVisual(bodyId);  // initial (in case ?<dim>= pre-checked nodes)
        }
        const TREE_ALL_LABEL = { material: 'All materials', context: 'All sampled features', object_type: 'All specimen types' };
        for (const [key, bodyId] of [['material', 'materialFilterBody'], ['context', 'contextFilterBody'], ['object_type', 'objectTypeFilterBody']]) {
            if (FACET_TREE) await renderTreeFacet(key, bodyId, grouped[key], TREE_ALL_LABEL[key]);
            else renderFilter(bodyId, key, grouped[key]);
        }
        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";
}

// === 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');
    const downloadBtn = document.getElementById('tableDownloadCsv');

    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 place = formatPlaceName(r.place_name);
                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"' : '';
                // #323: PID column (Andrea) — pids are long (ark:/28722/…), so
                // the cell ellipsizes via CSS with the full pid in title/hover.
                // Source URL column: an explicit external link to the sample's
                // landing page at its source repository. This does NOT reopen
                // #226 (which removed the *label* cell's href because click-
                // anywhere = open card): here the external link is its own
                // dedicated, honestly-labeled cell; activateRow ignores clicks
                // that originate inside an <a> so the row doesn't also fly.
                const rowSrcUrl = sourceUrl(r.pid);
                // Row-specific aria-label (Codex review): screen-reader users
                // tabbing the column hear WHICH record each identical
                // "record ↗" link opens.
                const srcUrlHtml = rowSrcUrl
                    ? `<a class="row-source-link" href="${escapeHtml(rowSrcUrl)}" target="_blank" rel="noopener noreferrer" title="Open this sample's record at its source repository" aria-label="Open record for ${safeLabel} at its source repository">record ↗</a>`
                    : '';
                // #311: material/context/object_type are URIs (from facets_url,
                // joined in loadPage()); resolve to human labels the same way
                // the facet tree and search results already do. context is
                // Andrea's "Sampled feature" (matches #291's facet-tree naming:
                // context -> Sampled Feature, object_type -> Specimen Type).
                const uriLabel = (uri) => uri
                    ? escapeHtml((typeof window !== 'undefined' && window.conceptLabelForUri)
                        ? window.conceptLabelForUri(uri) : uri)
                    : '';
                return `<tr data-pid="${pidAttr}"${selectedClass}>
                    <td>${tableSourceBadge(r.source)}</td>
                    <td>${labelHtml}</td>
                    <td class="pid-cell" title="${pidAttr}">${pidAttr}</td>
                    <td>${escapeHtml(place)}</td>
                    <td>${escapeHtml(r.result_time || '')}</td>
                    <td>${uriLabel(r.material)}</td>
                    <td>${uriLabel(r.object_type)}</td>
                    <td>${uriLabel(r.context)}</td>
                    <td>${escapeHtml(lat)}</td>
                    <td>${escapeHtml(lng)}</td>
                    <td>${srcUrlHtml}</td>
                </tr>`;
            }).join('');
            tableEl.innerHTML = `<div class="table-scroll">
                <table class="samples-table">
                    <thead><tr><th>Source</th><th>Label</th><th>PID</th><th>Place</th><th>Date</th><th>Material</th><th>Object type</th><th>Sampled feature</th><th>Lat</th><th>Lon</th><th>Source URL</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) => {
                    // #323: a click on the Source URL <a> (or any future in-row
                    // anchor) means "open the external record", not "select this
                    // row" — let the browser handle the link alone.
                    if (e && e.target && e.target.closest && e.target.closest('a')) return;
                    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.
                    writeGlobeHash(viewer, { force: true });
                    // 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.
            // #311: material/context/object_type come from facets_url (scalar
            // URI columns keyed by pid), joined AFTER paging (CTE) so the join
            // only ever touches TABLE_PAGE_SIZE rows, not a full facets scan.
            // Labels are resolved client-side via window.conceptLabelForUri()
            // in renderTable() rather than joining vocab_labels here too.
            const data = await db.query(`
                WITH page AS (
                    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}
                )
                SELECT page.*, f.material, f.context, f.object_type
                FROM page
                LEFT JOIN read_parquet('${facets_url}') AS f ON f.pid = page.pid
            `);
            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);
        }
    }

    // #312: "Download CSV" exports the CURRENT FILTERED result set (viewport
    // + source/facet/search filters), not just the visible page. Capped at
    // CSV_ROW_CAP rows so a broad/unfiltered export at world zoom can't hang
    // the tab on a multi-million-row pull; the meta line says so honestly
    // (same "honesty" convention as the rest of this table) rather than
    // silently truncating.
    const CSV_ROW_CAP = 50000;
    // #323: source_url appended LAST so existing consumers of the #312 column
    // order keep working; it's the same n2t.net resolver link the table's
    // "Source URL" column shows.
    const CSV_HEADERS = ['pid', 'source', 'label', 'place', 'date', 'material', 'object_type', 'sampled_feature', 'latitude', 'longitude', 'source_url'];

    function csvField(v) {
        let s = v == null ? '' : String(v);
        // Formula-injection hardening: a label/place_name is public data we
        // don't control, and this file is expected to land in Excel/Sheets.
        // A cell starting with =, +, -, or @ is interpreted as a formula
        // there — prefix with a single quote (a no-op in spreadsheet apps,
        // rendered as plain text) so no downstream formula ever executes.
        // Skipped for actual JS numbers (latitude/longitude): a negative
        // coordinate like -122.27 stringifies to "-122.27", which would
        // otherwise be misidentified as a formula and corrupted.
        if (typeof v !== 'number' && /^[=+\-@]/.test(s)) s = `'${s}`;
        // \r included (not just \n) — a bare carriage return in a field
        // still breaks row structure for RFC 4180 parsers (Codex review).
        return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
    }

    function csvRow(r) {
        const place = formatPlaceName(r.place_name);
        const labelFor = (uri) => uri
            ? ((typeof window !== 'undefined' && window.conceptLabelForUri) ? window.conceptLabelForUri(uri) : uri)
            : '';
        return [r.pid, r.source, r.label, place, r.result_time,
                 labelFor(r.material), labelFor(r.object_type), labelFor(r.context),
                 r.latitude, r.longitude, sourceUrl(r.pid) || ''].map(csvField).join(',');
    }

    let downloadInFlight = false;

    async function downloadCsv() {
        if (downloadInFlight || !downloadBtn) return;
        const bboxSQL = viewerBboxSQL('latitude', 'longitude', VIEWPORT_PAD_FACTOR);
        if (bboxSQL === null) {
            setMeta('No globe area in view; pan or zoom the globe before downloading.', true);
            return;
        }
        downloadInFlight = true;
        downloadBtn.disabled = true;
        const prevLabel = downloadBtn.textContent;
        downloadBtn.textContent = 'Preparing…';
        try {
            const where = `
                WHERE pid IS NOT NULL
                  ${sourceFilterSQL('source')}
                  ${facetFilterSQL()}
                  ${bboxSQL}
                  ${searchFilterSQL('pid')}
            `;
            const countData = await db.query(`SELECT COUNT(*) AS n FROM read_parquet('${lite_url}') ${where}`);
            const total = Number(Array.from(countData)[0]?.n ?? 0);
            if (total === 0) {
                setMeta('No samples match the current filters — nothing to download.', true);
                return;
            }
            const capped = total > CSV_ROW_CAP;
            const rowsData = await db.query(`
                WITH page AS (
                    SELECT pid, label, source, latitude, longitude, place_name, result_time
                    FROM read_parquet('${lite_url}')
                    ${where}
                    ORDER BY pid
                    LIMIT ${CSV_ROW_CAP}
                )
                SELECT page.*, f.material, f.context, f.object_type
                FROM page
                LEFT JOIN read_parquet('${facets_url}') AS f ON f.pid = page.pid
            `);
            const rows = Array.from(rowsData);
            const csv = [CSV_HEADERS.join(','), ...rows.map(csvRow)].join('\r\n');
            const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' });
            const url = URL.createObjectURL(blob);
            const a = document.createElement('a');
            a.href = url;
            a.download = `isamples-explorer-samples-${rows.length}${capped ? `-of-${total}` : ''}.csv`;
            document.body.appendChild(a);
            a.click();
            a.remove();
            URL.revokeObjectURL(url);
            setMeta(capped
                ? `Downloaded first ${rows.length.toLocaleString()} of ${total.toLocaleString()} matching samples as CSV — narrow your filters for a complete export.`
                : `Downloaded ${rows.length.toLocaleString()} samples as CSV.`);
        } catch (err) {
            console.error('CSV download failed:', err);
            setMeta('CSV download failed; adjust filters and try again.', true);
        } finally {
            downloadInFlight = false;
            downloadBtn.disabled = false;
            downloadBtn.textContent = prevLabel;
        }
    }

    if (downloadBtn) downloadBtn.addEventListener('click', downloadCsv);

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

// === 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)` : '';

    // #208/#267: the single predicate for "a filter is active that forces the
    // map into point mode." Pre-#300 this is BOTH text-search and any facet
    // (material/context/object_type) — the pre-aggregated H3 cluster summaries
    // carry only dominant_source, so they can't honor those filters; point mode
    // renders the actual filtered dots instead. This was duplicated verbatim at
    // four sites (camera.changed targetMode, the two filter-change handlers, and
    // the deep-link restore); centralizing it here is where the #300 rule change
    // (relax the FACET case above EXIT_POINT_ALT to filtered clusters) will live.
    const filtersForcePoint = () => searchIsActive() || hasFacetFilters();

    // #208/#300: the single authority that maps (altitude, latch) → target mode,
    // with the point/cluster hysteresis band.
    //   - search active → point (clusters can't be text-filtered, #234 C3)
    //   - facet active but filtered clusters NOT ready (pre-republish / preflight
    //     pending) → point, exactly as pre-#300 (#267): the summary clusters are
    //     facet-blind, so point mode renders the real filtered dots
    //   - otherwise the ALTITUDE hysteresis decides for both filtered and
    //     unfiltered (#300): facet-active cluster loads are filter-aware
    //     (loadRes aggregates off the masks), so clusters stay coherent
    //   - `latch` resolves the hysteresis band; defaults to the live mode, but a
    //     URL/back-forward restore passes the saved latch (Codex P1.7) so the band
    //     doesn't resolve to the mode of the view being LEFT
    const computeTargetMode = (alt, latch = getMode()) =>
        searchIsActive() ? 'point'
        : (hasFacetFilters() && !(typeof window !== 'undefined' && window.__filteredClustersReady === true)) ? 'point'
        : alt < ENTER_POINT_ALT ? 'point'
        : alt > EXIT_POINT_ALT ? 'cluster'
        : latch;

    // 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

    // #300: cancel any in-flight cluster load WITHOUT starting a successor. Bumping
    // loadResGen alone makes the in-flight loadRes discard its result, but that
    // call's `finally` only clears `loading` when ITS generation is still current
    // (it no longer is) — so `loading` would stay true forever and every later
    // camera handler's `!loading` reload guard would be wedged. Clear it here
    // (Codex round-2 P1.2). Used when a transition supersedes clusters without a
    // replacement load (entering point mode; a fresh hashchange).
    const invalidateClusterLoads = () => { ++loadResGen; loading = false; };

    // #300: wait for the DuckDB-WASM connection to go idle (no other queries in
    // flight) before issuing the heavy filtered-cluster aggregation — running it
    // amid boot's concurrent query storm deadlocks the MVP build. Post-boot this
    // resolves immediately (sparse queries); during boot it waits out the storm.
    // Capped so a never-idle connection can't strand the load. Only the filtered
    // path needs this; the light summary query is safe concurrent.
    async function whenConnectionIdle(capMs = 20000) {
        const t0 = performance.now();
        while ((typeof db._inFlight === 'function' ? db._inFlight() : 0) > 0
               && performance.now() - t0 < capMs) {
            await new Promise(r => setTimeout(r, 120));
        }
    }

    const loadRes = async (res, url, opts = {}) => {
        const gen = ++loadResGen;  // claim a generation
        loading = true;
        const filtered = wantFilteredClusters();      // #300: source vs filtered lite
        const sig = desiredClusterSig();              // #300: snapshot BEFORE the await
        updatePhaseMsg(opts.loadingMsg || `Loading H3 res${res}...`, 'loading');

        try {
            performance.mark(`r${res}-s`);
            // #300: gate the heavy filtered aggregation on an idle connection
            // (deadlock-avoidance); no-op for the light summary path.
            if (filtered) await whenConnectionIdle();
            // Re-check supersession after the idle wait (a newer load or a filter
            // change may have landed while we waited).
            if (gen !== loadResGen || sig !== desiredClusterSig()) return false;
            const data = await db.query(filtered ? filteredClusterSQL(res) : `
                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')}
            `);

            // Stale if a newer load superseded us (gen) OR the desired cluster
            // CONTENTS changed while we queried (filters toggled mid-flight) —
            // applying now would label the cache with the wrong filter sig
            // (Codex P0.2/P1.3).
            if (gen !== loadResGen || sig !== desiredClusterSig()) return false;
            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 };
            viewer._clusterFilterSig = sig;   // #300: label the cache with what it IS

            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;

        // #220: bbox via the shared `viewerBboxSQL()` (VIEWPORT_PAD_FACTOR padding),
        // the SAME helper the table uses (since #219). The previous inline padding
        // emitted a single `longitude BETWEEN padded.west AND padded.east`, which is
        // WRONG at the antimeridian: a viewport that wraps the dateline has
        // west > east (and, post-padding, `bounds.east - bounds.west` is negative, so
        // the inline lngPad math was meaningless too), so `BETWEEN a-larger AND a-
        // smaller` matched ZERO rows — point mode + the "Samples in View" count
        // (computed off the same WHERE) read 0 / undercounted near the dateline while
        // the table (via viewerBboxSQL) showed the correct set. viewerBboxSQL emits
        // the split `(lng BETWEEN west AND 180 OR lng BETWEEN -180 AND east)` for the
        // wrap case and also normalizes post-padding overflow back into [-180,180].
        const bboxSQL = viewerBboxSQL('latitude', 'longitude', VIEWPORT_PAD_FACTOR);
        if (!bboxSQL) return;  // off-globe (rare) — same bail as the !bounds guard

        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 1=1${bboxSQL}
                  ${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;
            // Coherence audit F5: when the cap is hit we do NOT know the in-view
            // total until the COUNT below succeeds. If it fails we must say so
            // rather than pass the cap off as the total (see below).
            let totalCountKnown = true;
            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 — but
                    // do NOT pretend the render cap is the true total. We hit
                    // POINT_BUDGET, so the real number is >= data.length and
                    // could be 10-100x higher. Reporting "5,000 samples in
                    // view" here is simply false (coherence audit F5; same bug
                    // shape #206 fixed for the no-failure case).
                    totalCountKnown = false;
                    console.warn("Real-count query failed; in-view total is unknown:", 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).
            // F5: '—' when the COUNT failed — the cap was hit, so the true
            // in-view total is unknown and definitely NOT samples.length.
            updateStats('Samples', samples.length, totalCountKnown ? totalCount : '—', `${(elapsed/1000).toFixed(1)}s`, 'Samples Rendered', 'Samples in View');
            const phaseMsg = !totalCountKnown
                ? `Showing ${samples.length.toLocaleString()} samples (display limit reached — total in view unavailable). Click one for details.`
                : 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');
            // F5: diagnostics must not assert the cap as the total either — a
            // dishonest debug log is how a future reader mis-diagnoses this.
            window.a1dbg?.('point-load-render', { rendered: samples.length, totalCount: totalCountKnown ? totalCount : null, totalCountKnown, searchActive: searchIsActive(), searchFiltered: !!searchFilterSQL('pid') });
            console.log(`Point mode: rendered ${samples.length} of ${totalCountKnown ? totalCount : 'unknown'} samples in ${elapsed.toFixed(0)}ms${capReached ? ' (cap reached)' : ''}${totalCountKnown ? '' : ' (count query failed)'}`);

        } 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) writeGlobeHash(viewer, { replace: false, force: true });
        // #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) writeGlobeHash(viewer, { replace: false, force: true });
        // 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();
        // #290/#291: in tree mode each dim participates in the live count engine via
        // its MINIMAL node selection (treeSelection) — but ONLY when zoomed in
        // (!isGlobalView). The membership COUNT(DISTINCT pid) query is a near-full
        // scan at global/near-global views and would starve the single DuckDB-WASM
        // connection (incl. the samples-table query); at global the static tree
        // baseline IS the correct global count, so we use it (instant). Its own
        // per-node counts + cross-filter contribution use the membership table (NOT
        // facets_v3's flat value) — see buildCrossFilterWhere + updateCrossFilteredCounts.
        const dimValues = (key) =>
            (treeActive(key) && !isGlobalView()) ? treeSelection(key)
          : (treeActive(key) ? [] : getCheckedValues(TREE_DIM_BODY[key]));
        const dims = [
            { key: 'source', col: 'source', values: sources.length < sourceTotal ? sources : [] },
            { key: 'material', col: 'material', values: dimValues('material') },
            { key: 'context', col: 'context', values: dimValues('context') },
            { key: 'object_type', col: 'object_type', values: dimValues('object_type') },
        ];
        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(',');
                // #290/#291: a tree dim's selection is a set of concept NODES —
                // constrain via the membership table (which encodes every ancestor)
                // so a selected parent matches its whole subtree, rather than
                // facets_v3's single flat value.
                if (treeActive(d.key)) {
                    return `${colPrefix}pid IN (SELECT pid FROM read_parquet('${membership_url}') WHERE facet_type='${d.key}' AND concept_uri IN (${list}))`;
                }
                return `${colPrefix}${d.col} IN (${list})`;
            });

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

    // #290/#293: the single active filter (one node/value in exactly ONE dim),
    // read DIRECTLY from the controls so it sees tree-node selections even at
    // global view (describeCrossFilters zeroes those). Returns {key, value} for a
    // source value or a single tree NODE; null otherwise (no filter, multi-value,
    // multi-dim, or a flat-mode dim — those keep their existing paths). The cube
    // is keyed by concept_uri for tree dims, so flat-mode dim selections are
    // deliberately excluded here (they'd miss the cube and fall through anyway).
    function effectiveSingleFilter() {
        const sel = [];
        const sourceTotal = document.querySelectorAll('#sourceFilter input[type="checkbox"]').length;
        const sources = getActiveSources();
        if (sources.length > 0 && sources.length < sourceTotal) sel.push({ key: 'source', values: sources });
        for (const key of TREE_DIM_KEYS) {
            if (!treeActive(key)) continue;           // flat-mode dim → not in this cube
            const vals = treeSelection(key);
            if (vals && vals.length > 0) sel.push({ key, values: vals });
        }
        if (sel.length === 1 && sel[0].values.length === 1) {
            return { key: sel[0].key, value: sel[0].values[0] };
        }
        return null;
    }

    // Apply cross-filtered counts for a single active filter from the precomputed
    // facet_tree_cross_filter cube. Returns true if counts were applied (or the
    // request was superseded mid-flight), false on a miss/error so the caller can
    // fall through to the existing paths. The cube's schema mirrors
    // facet_cross_filter: filter_<dim> columns + facet_type/facet_value/count.
    async function applyTreeCubeCounts(eff, dims, myReq) {
        const filterColForKey = {
            source: 'filter_source', material: 'filter_material',
            context: 'filter_context', object_type: 'filter_object_type',
        };
        const cols = ['filter_source', 'filter_material', 'filter_context', 'filter_object_type'];
        const targetCol = filterColForKey[eff.key];
        const value = escSql(eff.value);
        const where = cols.map(c => c === targetCol ? `${c} = '${value}'` : `${c} IS NULL`).join(' AND ');
        try {
            const rows = await db.query(`
                SELECT facet_type, facet_value, count
                FROM read_parquet('${tree_cross_filter_url}')
                WHERE ${where}
            `);
            if (myReq !== facetCountsReqId) return true;   // superseded — stop, don't fall through
            if (!rows || rows.length === 0) return false;  // miss — fall through
            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));
            }
            // The active dim shows ALL its own nodes (null = no cross-filter on self).
            for (const d of dims) applyFacetCounts(d.key, d.key === eff.key ? null : grouped[d.key]);
            return true;
        } catch (err) {
            console.warn('Tree cross-filter cube lookup failed; falling back to on-the-fly:', err);
            return false;
        }
    }

    // #304/#305: a DIRECT snapshot of every active selection read from the controls —
    // unlike describeCrossFilters(), it does NOT zero tree selections at global view
    // (that zeroing is the #304 root cause). Returns per-dim selected values (source
    // strings; tree concept_uris), an active-dim count, and the source-impossible
    // flag. Tree dims contribute only in full tree mode (flat dims keep facets_v3
    // paths). source: [] means "no constraint" (all or none selected — disambiguated
    // by sourceImpossible).
    function directFilterSnapshot() {
        const sourceTotal = document.querySelectorAll('#sourceFilter input[type="checkbox"]').length;
        const sources = getActiveSources();
        const sourceImpossible = sourceTotal > 0 && sources.length === 0;
        // a partial source selection is a real constraint; all/none → no positive list
        const sourceVals = (sources.length > 0 && sources.length < sourceTotal) ? sources : [];
        const snap = { source: sourceVals, sourceImpossible, material: [], context: [], object_type: [] };
        for (const key of TREE_DIM_KEYS) {
            if (treeActive(key)) snap[key] = treeSelection(key) || [];
        }
        // dims that impose a constraint (drives "is there anything to cross-filter?")
        let active = sourceImpossible || sourceVals.length > 0 ? 1 : 0;
        for (const key of TREE_DIM_KEYS) if (snap[key].length > 0) active++;
        snap.activeCount = active;
        return snap;
    }

    // #304/#305: build the cross-filter WHERE conditions over sample_facet_index
    // (alias-free; columns resolve to the index) for the OTHER active dims, EXCLUDING
    // `excludeKey` (exclude-self). Tree dims → `(<dim>_mask & <orMask>) <> 0` from the
    // node_bits bit map; source → `source IN (...)`. Returns null if a tree selection
    // can't be turned into a mask (bit map absent / unknown node) so the caller can
    // bail honestly instead of under-constraining. A source-impossible state zeroes
    // every NON-source target (the source dim's own histogram still computes).
    function maskIndexWhere(snap, excludeKey) {
        // #304/#305: the count path uses __nodeBitsMap (valid as soon as node_bits is)
        // — NOT __nodeBits, which is gated on the masks FILTER artifact (Codex #4).
        const bits = (typeof window !== 'undefined') ? window.__nodeBitsMap : null;
        const conds = [];
        for (const key of TREE_DIM_KEYS) {
            if (key === excludeKey) continue;
            const sel = snap[key];
            if (!sel || sel.length === 0) continue;
            if (!bits || !bits[key]) return null;
            let mask = 0n;
            for (const uri of sel) {
                const idx = bits[key].get(uri);
                if (idx === undefined) return null;           // unknown node → bail
                mask |= (1n << BigInt(idx));
            }
            if (mask === 0n) return null;
            // s.-qualified: Phase 3 JOINs samples_map_lite (which ALSO has a `source`
            // column) for viewport scoping, so unqualified `source` would be ambiguous.
            // Mask columns exist only on the index, but qualify everything for clarity.
            conds.push(`(s.${key}_mask & ${mask}) <> 0`);      // BigInt → decimal BIGINT literal
        }
        if (excludeKey !== 'source') {
            if (snap.sourceImpossible) return ['1=0'];          // no source selectable → 0 for tree targets
            if (snap.source.length > 0) {
                conds.push(`s.source IN (${snap.source.map(v => `'${escSql(v)}'`).join(',')})`);
            }
        }
        return conds;
    }

    // #304/#305: compute multi-filter cross-filtered counts for ALL dims off the
    // complete per-pid index and apply them ATOMICALLY after a single stale check.
    // Returns: 'ok' (applied), 'superseded' (a newer request won), 'unavailable'
    // (index/bitmap usable but a query failed → honesty: caller shows the dash), or
    // 'fallthrough' (index/bitmap not usable yet — status 'pending' or 'failed' —
    // caller uses legacy paths / facetCountsDisplayState decides Loading vs dash, #313).
    async function applyMaskIndexCounts(snap, dims, myReq, bboxSQL = null) {
        if (window.__facetIndexStatus !== 'ready' || !window.__nodeBitsMap) return 'fallthrough';
        // Build ONE query (UNION ALL of per-dim arms) rather than 4 concurrent
        // full-index scans — the documented DuckDB-WASM single-connection
        // starvation risk (Codex P2). One statement = one connection slot. Each arm
        // carries its OWN exclude-self cross-filter WHERE. Common output shape
        // (dim, value, count) so one pass groups them.
        //
        // #305 Phase 3 — viewport + search: the index carries no coordinates, so a
        // viewport-scoped count JOINs samples_map_lite (l.latitude/l.longitude) on
        // pid (one row/pid → no grain change) and appends the SAME padded bbox the
        // table/heatmap use; an active search appends the search_pids semi-join.
        // bboxSQL (when set) is already built against l.latitude/l.longitude by the
        // caller. These are bare predicates (no leading AND) so the WHERE assembles
        // cleanly even when there is no cross-filter constraint (viewport-only).
        const liteJoin = bboxSQL ? `JOIN read_parquet('${lite_url}') l ON l.pid = s.pid` : '';
        const bboxBare = bboxSQL ? bboxSQL.replace(/^\s*AND\s+/i, '') : null;
        const searchBare = searchIsActive() ? 's.pid IN (SELECT pid FROM search_pids)' : null;
        const buildWhere = (conds, extra = []) => {
            const preds = [...conds, ...extra];
            if (bboxBare) preds.push(bboxBare);
            if (searchBare) preds.push(searchBare);
            return preds.length ? `WHERE ${preds.join(' AND ')}` : '';
        };
        const arms = [];
        for (const d of dims) {
            const conds = maskIndexWhere(snap, d.key);
            if (conds === null) return 'unavailable';   // selected node missing a bit → can't compute honestly
            if (d.key === 'source') {
                // source target: COUNT(*) per source over the index (one row/pid),
                // constrained by the tree dims only (exclude-self) + viewport/search.
                arms.push(`SELECT 'source' AS dim, s.source AS value, COUNT(*) AS count
                           FROM read_parquet('${index_url}') s ${liteJoin}
                           ${buildWhere(conds, ['s.source IS NOT NULL'])} GROUP BY s.source`);
            } else {
                // tree target: JOIN node_bits; each (pid,node) the pid is a member of
                // yields one row, so COUNT(*) per concept_uri == distinct pids with
                // that bit. Membership encodes ancestor closure → parent ≥ child.
                arms.push(`SELECT '${d.key}' AS dim, nb.concept_uri AS value, COUNT(*) AS count
                           FROM read_parquet('${index_url}') s
                           JOIN read_parquet('${node_bits_url}') nb
                             ON nb.facet_type = '${d.key}'
                            AND (s.${d.key}_mask & (1::BIGINT << nb.bit_index)) <> 0
                           ${liteJoin}
                           ${buildWhere(conds)} GROUP BY nb.concept_uri`);
            }
        }
        try {
            const rows = await db.query(arms.join('\nUNION ALL\n'));
            if (myReq !== facetCountsReqId) return 'superseded';
            const grouped = { source: new Map(), material: new Map(), context: new Map(), object_type: new Map() };
            for (const r of rows) if (grouped[r.dim]) grouped[r.dim].set(r.value, Number(r.count));
            // atomic repaint: all dims at once, only after the single stale check
            for (const d of dims) applyFacetCounts(d.key, grouped[d.key]);
            return 'ok';
        } catch (err) {
            if (myReq !== facetCountsReqId) return 'superseded';
            console.warn('mask-index cross-filter counts failed; counts unavailable (not baseline):', err);
            return 'unavailable';
        }
    }

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

        // #290/#293 TREE cross-filter cube fast-path. At (near-)global view, a
        // SINGLE active filter — one node in any one dim — is answered instantly
        // by the precomputed facet_tree_cross_filter cube, replacing the live
        // membership COUNT(DISTINCT pid) self-scan that hits the DuckDB-WASM
        // data-scale wall. CRITICAL: describeCrossFilters() intentionally ZEROES
        // tree-dim selections at global view (so activeDims excludes them), which
        // is exactly why a selected tree node otherwise fails to cross-filter the
        // other dims at global view (#290). We therefore read the effective single
        // filter (incl. tree nodes) DIRECTLY here, ahead of the baseline early-
        // return. Gated to global view (bboxSQL===null; viewport needs live
        // counts) and no active search (the cube is global, can't be pid-scoped).
        // Any miss/error (incl. cube not yet published) returns false → falls
        // through to the existing baseline / flat-cube / slow paths unchanged.
        // GATE: only when ALL tree dims are rendered as trees (full tree mode —
        // the deployed default). In flat mode (?facets=flat) the cube's subtree-
        // membership semantics would be WRONG for a flat dim (it counts a sample
        // under ancestor nodes it never directly asserts), and a flat-mode
        // selection isn't representable in the cube — so we defer entirely to the
        // flat-cube/slow paths (no flat-count regression). (Codex P1.)
        // SCOPE NOTE (Codex r2): the degenerate "mixed" state (FACET_TREE on but
        // one tree failed to render) also fails this gate and falls through to the
        // pre-cube baseline path — i.e. the SAME behavior as before this cube
        // existed (no regression). Cross-filtering that transient state is out of
        // scope; the cube's contract is full-tree-mode + global view + one filter.
        if (bboxSQL === null && !searchIsActive() && !sourceImpossible
            && TREE_DIM_KEYS.every(treeActive)) {
            const eff = effectiveSingleFilter();
            if (eff && await applyTreeCubeCounts(eff, dims, myReq)) return;
            if (myReq !== facetCountsReqId) return;
        }

        // #304/#305: route facet counts through the complete per-pid index whenever
        // there is ANY constraint (cross-filter, viewport, or search) in full tree
        // mode. Phase 2 covered global+no-search multi-filter; Phase 3 extends the
        // SAME index path to VIEWPORT (JOIN samples_map_lite + padded bbox) and
        // SEARCH (search_pids semi-join). The single-filter cube above stays a pure
        // global fast-path optimization.
        //
        // FALLBACK SEMANTICS differ by view (the honesty rule). The pivot is whether
        // a viewport bbox exists, NOT whether search is active (Codex P3):
        //  - GLOBAL (bboxSQL === null), with OR without search: the legacy tree path
        //    below hits `if (treeActive && !bboxSQL) applyFacetCounts(d.key, null)` —
        //    the unfiltered BASELINE — which IGNORES search and the cross-filters
        //    (#304). There is NO correct legacy global tree path. So on index
        //    miss/error at global we show "Loading…" (index still booting, #313) or
        //    the "unavailable" dash (index load genuinely failed) — NEVER baseline.
        //    (__onFacetIndexReady re-runs this when readiness flips → real counts.)
        //  - VIEWPORT (bboxSQL !== null), ±search: the legacy membership path JOINs
        //    samples_map_lite + bbox + the search semi-join and is CORRECT, so an
        //    index miss/error falls through to it (both paths coexist until the
        //    membership path is retired — after in-app parity is confirmed).
        if (TREE_DIM_KEYS.every(treeActive)) {
            const snap = directFilterSnapshot();
            const hasConstraint = snap.activeCount >= 1 || bboxSQL !== null || searchIsActive();
            if (hasConstraint) {
                const res = await applyMaskIndexCounts(snap, dims, myReq, bboxSQL);
                if (res === 'superseded' || res === 'ok') return;
                if (myReq !== facetCountsReqId) return;   // defensive stale check (Codex)
                if (bboxSQL === null) {
                    // global (incl. global+search): no correct legacy tree path →
                    // #313 P0: distinguish "index still loading" (Loading…, real
                    // counts are still coming) from "index load genuinely failed
                    // this session" (the honest dash) — NEVER baseline (#304).
                    const displayState = facetCountsDisplayState(window.__facetIndexStatus, res);
                    if (displayState === 'pending') markFacetCountsPending();
                    else markFacetCountsUnavailable();
                    return;
                }
                // viewport (±search): fall through to the correct legacy membership path
            }
        }

        // 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;
        // #290: the cube (facet_cross_filter) is pre-aggregated over flat facet
        // values and has no tree nodes, so it can't answer Material tree counts
        // (nor a Material-node cross-filter). In tree mode, always take the slow
        // path; the common global-no-filter case is still fast via the baseline
        // early-return above (material baseline = the global tree counts).
        if (singleActiveDim && totalActiveValues === 1 && bboxSQL === null && !searchIsActive() && !TREE_DIM_KEYS.some(treeActive)) {
            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 (treeActive(d.key) && !bboxSQL) {
                    // #290/#291: global / near-global view → the static tree baseline
                    // IS the correct global count (instant). Avoids a near-full-scan
                    // membership query that would starve the WASM connection.
                    applyFacetCounts(d.key, null);
                    return;
                }
                if (treeActive(d.key)) {
                    // #290/#291: live tree counts from membership — COUNT(DISTINCT pid)
                    // per concept node for this dim, scoped to viewport (bbox via lite
                    // JOIN) + the OTHER active dims + search. NOT filtered by this dim's
                    // own selection (show all nodes' counts); distinct-pid so ancestor
                    // rows don't inflate. Parent ≥ child holds. Each OTHER active dim is
                    // a pid-subquery (tree dim → membership; flat dim → facets_v3).
                    const others = activeDims.filter(x => x.key !== d.key);
                    let otherCond = '';
                    if (sourceImpossible) {
                        otherCond = ' AND 1=0';
                    } else if (others.length) {
                        otherCond = ' AND ' + others.map(x => {
                            const list = x.values.map(v => `'${escSql(v)}'`).join(',');
                            return treeActive(x.key)
                                ? `m.pid IN (SELECT pid FROM read_parquet('${membership_url}') WHERE facet_type='${x.key}' AND concept_uri IN (${list}))`
                                : `m.pid IN (SELECT DISTINCT pid FROM read_parquet('${facets_url}') WHERE ${x.col} IN (${list}))`;
                        }).join(' AND ');
                    }
                    if (bboxSQL) {
                        rows = await db.query(`
                            SELECT m.concept_uri AS value, COUNT(DISTINCT m.pid) AS count
                            FROM read_parquet('${membership_url}') m
                            JOIN read_parquet('${lite_url}') l ON l.pid = m.pid
                            WHERE m.facet_type='${d.key}'${otherCond}${bboxSQL}${searchFilterSQL('m.pid')}
                            GROUP BY m.concept_uri
                        `);
                    } else {
                        rows = await db.query(`
                            SELECT m.concept_uri AS value, COUNT(DISTINCT m.pid) AS count
                            FROM read_parquet('${membership_url}') m
                            WHERE m.facet_type='${d.key}'${otherCond}${searchFilterSQL('m.pid')}
                            GROUP BY m.concept_uri
                        `);
                    }
                } else 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);
                // Coherence audit F3 / PLAN_305 Phase 4 ("remove the misleading
                // active-filter baseline fallback everywhere"). The old Q3
                // behavior painted applyFacetCounts(d.key, null) — the
                // UNFILTERED global baseline — when this query threw. Under
                // active filters that is a confidently wrong number with no
                // signal: the repaint even clears `.recomputing`, so it looks
                // settled. That is the #304/#340 failure mode in miniature.
                // Honest dash instead. (Under NO active constraint the baseline
                // would have been correct, but this catch is only reachable on
                // the constrained path, so the dash is the safe answer.)
                markFacetCountsUnavailable([d.key]);
            }
        }));
    }

    function refreshFacetCounts() {
        clearTimeout(facetCountsDebounce);
        const myReq = ++facetCountsReqId;
        // #340 (grant closeout): under a committed search the count recompute
        // NEVER settles — verified live on prod 2026-08-04. The search+bbox arm
        // of applyMaskIndexCounts leaves its promise pending, so nothing ever
        // calls applyFacetCounts / markFacetCountsUnavailable / -Pending, and
        // markFacetCountsRecomputing()'s class-only repaint leaves the PREVIOUS
        // (unfiltered, global) numbers on screen indefinitely. That is exactly
        // the misleading baseline #304 forbids and Eric asked us to never show.
        //
        // Search-aware cross-filtered counts are PLAN_305 Phase 3, which is not
        // being finished in the grant period. So we stop attempting them and
        // apply the honesty rule directly: an active search means counts are
        // unavailable. Bailing BEFORE the debounce also invalidates in-flight
        // requests via ++facetCountsReqId above, so a late-settling older query
        // cannot overwrite the dash. Clearing the search takes the normal path
        // again and restores real counts.
        if (searchIsActive()) {
            markFacetCountsUnavailable();
            return;
        }
        facetCountsDebounce = setTimeout(() => {
            // Re-check at FIRE time, not just schedule time: search can go active
            // during the 250 ms window (the producers call us on activation, but
            // this keeps the invariant local and true regardless of caller).
            if (searchIsActive()) { markFacetCountsUnavailable(); return; }
            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 = '';
                        // #172 Inc 1 (Codex round-2/round-5): list teardown → clear
                        // the pin snapshot too AND advance _panelGen (unified rule)
                        // so a slow in-flight search can't resurrect this list.
                        if (viewer.searchResultPoints) viewer.searchResultPoints.removeAll();
                        viewer._panelGen++;
                        writeGlobeHash(viewer, { force: true });
                    } 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 = '';
                        // #172 Inc 1 (Codex round-2/round-5): source filter
                        // invalidated the selected search result and cleared the
                        // list → clear its pins too AND advance _panelGen (unified
                        // rule) so a slow in-flight search can't resurrect it.
                        if (viewer.searchResultPoints) viewer.searchResultPoints.removeAll();
                        viewer._panelGen++;
                        writeGlobeHash(viewer, { force: true });
                    }
                }
            }

            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).
    // #300: drive the globe to the altitude- and filter-appropriate mode after a
    // facet or search change — the single transition path shared by both
    // filter-change handlers. Honors computeTargetMode:
    //   - point: render the real filtered dots (search at any zoom; facets below
    //     EXIT, or whenever filtered clusters aren't ready)
    //   - cluster: render the FILTERED h3 clusters (facets above EXIT, once ready)
    async function reconcileGlobeForFilters() {
        const h = viewer.camera.positionCartographic.height;
        if (computeTargetMode(h) === 'point') {
            // Invalidate any in-flight cluster load so a stale loadRes can't paint
            // clusters/stats under point mode — a search activation may start no
            // newer loadRes of its own (Codex P1.4). Use the helper so `loading`
            // is cleared too (P1.2).
            invalidateClusterLoads();
            if (getMode() !== 'point') await enterPointMode(false);
            else await loadViewportSamples();            // re-filter the dots in place
        } else {
            // Dedup: if we're already in cluster mode showing the right filtered
            // layer, there's nothing to do. Makes redundant reconciles (boot +
            // readiness hook + setTimeout0 all firing) cheap no-ops instead of
            // re-running the heavy filtered aggregation (Codex serialization-review).
            if (getMode() === 'cluster' && viewer._clusterFilterSig === desiredClusterSig()) return;
            // Target is clusters at this altitude. Load FIRST (into the hidden h3
            // layer while still in point mode), and only drop point mode if the
            // load applied — so a failed/superseded filtered load never exposes
            // stale clusters (Codex P1.10). loadRes is filter-aware: with a facet
            // active + ready it aggregates the FILTERED set off the masks.
            const res = h > 3000000 ? 4 : h > 300000 ? 6 : 8;
            const wasPoint = getMode() === 'point';
            const applied = await loadRes(res, { 4: h3_res4_url, 6: h3_res6_url, 8: h3_res8_url }[res]);
            if (!applied) return;                        // keep current mode; no stale flash
            if (wasPoint) exitPointMode(false);
            // Supersession invariant: a zoom below ENTER during the load still
            // lands in point mode (Codex P1.4).
            await tryEnterPointModeIfNeeded();
        }
    }

    async function handleFacetFilterChange() {
        busyAcquire();
        // #300: capture the freshness token at ENTRY (like the source handler), so
        // a second facet toggle during the reconcile await invalidates this run's
        // later selection revalidation instead of hydrating stale cluster metadata
        // (Codex round-2 P1.8).
        const isStale = freshSelectionToken(viewer);
        try {
            syncFacetNote();
            writeQueryState();
            refreshHeatmap();
            // #267/#300: a facet selection must visibly drive the MAP. Above
            // EXIT_POINT_ALT (once filtered clusters are ready) the map shows the
            // FILTERED h3 clusters; below it, the real filtered dots. The shared
            // reconcile picks the right mode from the current altitude + filter
            // state (and reloads filtered clusters in place when already in
            // cluster mode, since the filter set changed).
            await reconcileGlobeForFilters();
            refreshFacetCounts();

            // #300: a selected cluster card may now be stale — the facet change
            // can empty the cell (then drop the selection) or change its filtered
            // count/dominant_source. Revalidate via the (now filter-aware)
            // fetchClusterByH3, mirroring the source-filter handler (Codex P1.8).
            // Guarded by the entry-captured freshness token so a rapid second
            // toggle wins.
            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 = '';
                    // #172 Inc 1 (Codex round-2/round-5): list teardown → clear the
                    // pin snapshot too AND advance _panelGen (unified rule).
                    if (viewer.searchResultPoints) viewer.searchResultPoints.removeAll();
                    viewer._panelGen++;
                    writeGlobeHash(viewer, { force: true });
                } else {
                    await hydrateClusterUI(meta, isStale);
                }
            }
            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/#300: search always latches point mode (clusters can't be
            // text-filtered). Clearing search must NOT revert to clusters if a
            // facet is still active — but at world zoom that now means FILTERED
            // clusters, not point mode. The shared reconcile resolves all of this
            // from the live search + facet + altitude state.
            await reconcileGlobeForFilters();
            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);

    // #300: filtered clusters may become usable AFTER the page already has a facet
    // active — the lite preflight resolves asynchronously, or a republished lite
    // lands on a later visit. When that readiness flips true, reconcile the globe
    // so a world-zoom filtered view switches from forced point mode to filtered
    // clusters without needing a camera nudge (Codex P1.9). The preflight cell
    // invokes this hook; if it resolved BEFORE this watcher registered the hook,
    // the deferred guarded check below catches it (and no-ops if boot already set
    // the right mode). Any later camera/moveEnd settle is a further backstop.
    // NB: no `!loading` guard here — db.query is serialized (see the `db` cell),
    // so a redundant reconcile can't deadlock; reconcileGlobeForFilters early-exits
    // when the cluster layer already matches the desired filter. A `!loading` guard
    // would be LOSSY: readiness arriving while an older unfiltered load is in flight
    // would skip the only reconcile signal permanently (Codex serialization-review P1).
    window.__onFilteredClustersReady = () => {
        if (hasFacetFilters()) reconcileGlobeForFilters();
    };
    // #304/#305: when the facet-index preflight settles true AFTER boot already
    // computed counts (async race), recompute so any filter that fell back to the
    // "unavailable" dash becomes correct counts without a user action. Refresh
    // UNCONDITIONALLY — hasFacetFilters() excludes SOURCE selections (Codex r2 P1),
    // and refreshFacetCounts is debounced + facetCountsReqId-guarded, so a redundant
    // no-filter refresh just recomputes the baseline harmlessly.
    window.__onFacetIndexReady = () => { refreshFacetCounts(); };
    setTimeout(() => {
        if (window.__filteredClustersReady === true && hasFacetFilters()) {
            const h = viewer.camera.positionCartographic.height;
            // Reconcile if the mode is wrong OR the cached cluster layer is still
            // summary (facet-blind) data — at world zoom both modes read 'cluster'
            // yet the layer needs to become FILTERED (Codex round-2 P1.4).
            if (computeTargetMode(h) !== getMode() || viewer._clusterFilterSig !== desiredClusterSig()) {
                reconcileGlobeForFilters();
            }
        }
    }, 0);

    // --- Shared settled-camera tail (#208 smell 1b) ---
    // The single reconciliation entry point both settled-camera listeners run
    // once the camera has come to rest: refresh the cluster-mode "Samples in
    // View" stat for the current viewport, then write the URL hash. Extracted
    // so `moveEnd` runs the SAME cluster-stat refresh that `camera.changed`
    // does — closing the sub-10%-pan gap where a small drag in cluster mode
    // updated the URL (moveEnd fires) but left the "Samples in View" count
    // stale (camera.changed's `percentageChanged=0.1` debounce didn't fire).
    //
    // Scope is deliberately minimal (Codex Q3, REFACTOR_PR4_PLAN.md §3): this
    // touches NEITHER the mode-transition / resolution-reload logic (which
    // stays camera.changed-only) NOR the facet/heatmap/point-exit logic (which
    // stays moveEnd-only). The cluster-stat read is synchronous and cheap
    // (counts already-loaded `_clusterData` against the padded viewport) and
    // no-ops unless we're in cluster mode with data loaded.
    function reconcileSettledCamera(v) {
        // Cluster-mode viewport count only — point mode shows its own count via
        // loadViewportSamples(). Padded bbox so the cluster "Samples in View"
        // stat matches the samples table row total (issue #221 round 2).
        if (getMode() === 'cluster' && v._clusterData) {
            // Coherence audit M2 + Codex review. Counting `_clusterData` says
            // nothing about whether that cache is CURRENT. It can be a previous
            // filter's cells, a previous resolution's cells, or the facet-blind
            // summary cache, while a reload is in flight or has just failed.
            // Painting from it would replace an honest "Loading H3…" or
            // "Failed to load…" with a green settled count — turning a visible
            // problem into a confident wrong number, which is precisely the
            // failure class this audit exists to remove. So: only speak when
            // the cache is provably current; otherwise stay quiet and let the
            // loading/failure message stand.
            const alt = v.camera.positionCartographic.height;
            const targetRes = alt > 3000000 ? 4 : alt > 300000 ? 6 : 8;
            const cacheIsCurrent = !loading
                && computeTargetMode(alt) === 'cluster'
                && currentRes === targetRes
                && v._clusterFilterSig === desiredClusterSig();
            if (cacheIsCurrent) {
                const inView = countInViewport(paddedViewportBounds(VIEWPORT_PAD_FACTOR));
                const total = v._clusterTotal;
                if (total) {
                    updateStats(`H3 Res${currentRes}`, `${inView.clusters.toLocaleString()} / ${total.clusters.toLocaleString()}`, inView.samples.toLocaleString(), null, 'Clusters in View / Loaded', 'Samples in View');
                }
                // M2 proper: exitPointMode() writes "N clusters in view" into the
                // ALWAYS-VISIBLE phase message, but this settle path previously
                // refreshed only the (collapsed-by-default) stats panel — so after
                // leaving point mode, the next ordinary pan stranded a previous
                // viewport's count on screen, stated as fact.
                updatePhaseMsg(`${inView.clusters.toLocaleString()} clusters in view. Zoom closer for individual samples.`, 'done');
            }
        }
        // _suppressHashWrite-gated default — the hashchange-flight path stays
        // unaffected (same gate the two raw writers honored before).
        writeGlobeHash(v);
    }

    // --- 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.
            writeGlobeHash(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 = computeTargetMode(h);

            if (targetMode === 'point' && getMode() !== 'point') {
                if (filtersForcePoint()) {
                    // 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') {
                // point→cluster (e.g. zoom out past EXIT with a facet active →
                // FILTERED clusters, #300). Load into the hidden h3 layer FIRST,
                // then drop point mode, so a failed/superseded load never flashes
                // stale clusters (Codex P1.10). Reload when the resolution OR the
                // filter signature changed; if neither, the cached clusters are
                // already correct and we just switch layers.
                const target = h > 3000000 ? 4 : h > 300000 ? 6 : 8;
                const needLoad = (target !== currentRes || viewer._clusterFilterSig !== desiredClusterSig()) && !loading;
                const applied = needLoad
                    ? await loadRes(target, { 4: h3_res4_url, 6: h3_res6_url, 8: h3_res8_url }[target])
                    : true;
                if (applied) {
                    exitPointMode();
                    // The user may have crossed below ENTER_POINT_ALT while this
                    // load was in flight; reconcile so no extra camera nudge is
                    // required. Skip on non-applied returns (issue #193): a stale
                    // return is recovered by the supersedor's chase, and a failed
                    // return leaves point mode + the error message intact (P1.10).
                    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 — reload if the resolution OR the filter signature
                // changed. The sig check makes a facet toggle that lands here
                // (already in cluster mode at the same res) refresh the FILTERED
                // clusters instead of leaving the previous filter's cells (#300).
                const target = h > 3000000 ? 4 : h > 300000 ? 6 : 8;
                if ((target !== currentRes || viewer._clusterFilterSig !== desiredClusterSig()) && !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();
                }
            }

            // Settled-camera tail: cluster "Samples in View" stat (cluster
            // mode only; point mode already shows viewport count) + URL-hash
            // replaceState for continuous movement. Shared with `moveEnd` via
            // reconcileSettledCamera() (#208 smell 1b).
            reconcileSettledCamera(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(async () => {
        // Settled-camera tail shared with `camera.changed` (#208 smell 1b):
        // URL-hash write + cluster "Samples in View" refresh. moveEnd fires on
        // every discrete settle including sub-10% pans that `camera.changed`
        // debounces away, so routing through here keeps the cluster stat in
        // lockstep with the URL (which moveEnd already kept fresh via #204).
        reconcileSettledCamera(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 + #300: route the sub-10% zoom-out transition
        // through computeTargetMode so it matches `camera.changed`. Search keeps
        // point mode LATCHED (computeTargetMode → 'point' while a search is
        // active) so the post-search flyTo can't bounce to clusters. A facet at
        // world zoom now targets FILTERED clusters instead of staying in point.
        if (computeTargetMode(h) === 'cluster') {
            // Sub-10% zoom-out from point mode (e.g. 175 km → 181 km) won't fire
            // `camera.changed`, so without driving the transition here we'd be
            // stuck in point mode above `EXIT_POINT_ALT` until a larger move.
            // Unlike the old unfiltered path, point mode never loaded FILTERED
            // clusters, so reload when the cached cluster signature doesn't match
            // the current filter (#300). Load into the hidden h3 layer first,
            // then exit — no stale-cluster flash on a failed load (P1.10).
            const res = h > 3000000 ? 4 : h > 300000 ? 6 : 8;
            const needLoad = res !== currentRes || viewer._clusterFilterSig !== desiredClusterSig();
            const applied = needLoad
                ? await loadRes(res, { 4: h3_res4_url, 6: h3_res6_url, 8: h3_res8_url }[res])
                : true;
            if (applied) {
                exitPointMode();
                // An overlapping settle may have moved the camera below
                // ENTER_POINT_ALT during the load await; chase so we re-enter
                // point mode instead of stranding the user in clusters at point
                // altitude (Codex round-2 P1.6 — the established invariant).
                await tryEnterPointModeIfNeeded();
            }
            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).
            //
            // #300: when a facet is active and filtered clusters are ready, the
            // visible cell is the FILTERED aggregate, so hydrate from the same
            // single-cell aggregation off lite (count / center / dominant_source
            // over the filtered subset) — otherwise the card would show the cell's
            // full unfiltered count and could even resolve a cell that the filter
            // excludes entirely (Codex P1.8). Empty under the filter → sample_count
            // 0 → treated as absent below.
            const result = await db.query(wantFilteredClusters() ? `
                WITH base AS (
                    SELECT source, latitude, longitude FROM read_parquet('${lite_url}')
                    WHERE h3_res${res} = CAST('${decimal}' AS UBIGINT)${sourceFilterSQL('source')}${facetFilterSQL()}
                )
                SELECT (SELECT COUNT(*) FROM base)::INTEGER AS sample_count,
                       (SELECT ROUND(AVG(latitude), 6) FROM base) AS center_lat,
                       (SELECT ROUND(AVG(longitude), 6) FROM base) AS center_lng,
                       (SELECT source FROM base GROUP BY source ORDER BY COUNT(*) DESC, source ASC LIMIT 1) AS dominant_source,
                       (SELECT COUNT(DISTINCT source) FROM base)::INTEGER AS source_count
            ` : `
                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];
            // #300: filtered aggregation always returns one row; a cell empty under
            // the active filter has sample_count 0 → treat as absent.
            if (!r.sample_count) return null;
            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;
        // #172 Inc 1 (Codex round-4 P1): claim panel ownership so an older
        // in-flight search render bails instead of overwriting these rows.
        const myPanelGen = ++viewer._panelGen;
        updateClusterCard(meta);
        const sampEl = document.getElementById('samplesSection');
        if (sampEl) sampEl.innerHTML = '<div style="text-align: center; color: #999; padding: 12px;">Loading nearby samples...</div>';
        // #172 Inc 1 (Codex round-2 P1, snapshot semantics): replacing the list
        // with nearby samples tears down any search-results list, so the
        // result-pin overlay (its snapshot) goes with it. This choke point
        // covers source/facet revalidation, hashchange h3 restore, and boot.
        if (viewer.searchResultPoints) viewer.searchResultPoints.removeAll();
        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;
            // #172 Inc 1 (Codex round-4 P1): only write if this hydration still
            // owns the panel — closes the reverse race with a search that
            // started earlier but resolves later. (round-3 P1): list + pins as
            // ONE owned operation, no await between guard, re-clear, and write.
            if (!panelWriteAllowed(myPanelGen, viewer._panelGen)) return;
            if (viewer.searchResultPoints) viewer.searchResultPoints.removeAll();
            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>';
        }
    }

    // --- Open the in-map detail card for a deep-linked sample (issue #285) ---
    // A `#pid=` deep-link (cold boot OR back/forward hashchange) must reach the
    // same end state as a table row-click: not just the sidebar card
    // (updateSampleCard / #clusterSection) but also the floating in-map detail
    // card (#inMapCard). This mirrors activateRow's tail (the rich wide-table
    // detail query → updateSampleDetail + populateInMapCardDetail), shared
    // between the boot and hashchange pid paths.
    //
    // We do NOT fly the camera here: both callers have already framed it to the
    // URL coordinates (boot setView / the hashchange flyTo above), and a `#pid=`
    // link is generated by Share / row-click with the camera captured AT the
    // sample (activateRow's pushState is replaced by the post-flight moveEnd
    // replaceState, so the history entry settles on the sample view). So we
    // anchor the card at canvas centre — exactly where the sample lands, the
    // same anchor activateRow uses to dodge the #226 lazy-load race (the
    // deferred-to-flyTo.complete approach was rejected there).
    //
    // Deliberate decision (issue #285 acceptance allows it): for a hand-edited
    // `#pid=` URL whose lat/lng do NOT point at the sample, the card still
    // anchors at canvas centre rather than flying. Adding a "camera far from
    // sample → flyTo" branch would fight the hashchange flyTo above and the
    // boot setView; it's a tracked follow-up, not folded in here.
    // `screenPos` (added #172 Inc 1): anchor the card at an explicit pixel —
    // used by the result-pin click, which frames the card at the click point
    // like the on-globe sample click. Omitted by the deep-link/hashchange
    // callers, which keep the canvas-centre anchor described above.
    async function openInMapCardForSample(meta, isStale, screenPos) {
        const canvas = viewer.scene.canvas;
        showInMapCard(meta, screenPos || { x: canvas.clientWidth / 2, y: canvas.clientHeight / 2 });
        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('Deep-link in-map detail query failed:', err);
            updateSampleDetail(null);
            populateInMapCardDetail(null);
        }
    }

    // --- 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);
        // #300: also invalidate any in-flight cluster load from a PRIOR
        // hashchange's restore callback, so it discards on its generation check
        // instead of replacing points/cache/stats/currentRes for the superseded
        // hash before the late isStale() guard fires (Codex round-2 P1.7).
        invalidateClusterLoads();
        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;   // release first (unconditional, as before)
            if (isStale()) return;               // a newer hashchange superseded us (P1.6)
            const s = readHash();
            // #300/#234 C3: resolve the restored mode through computeTargetMode.
            // Search still forces point; a facet at world zoom now restores to
            // FILTERED clusters instead of point. The hash encodes point
            // explicitly and cluster by omission, so pass `s.mode` as the
            // hysteresis latch — the band must resolve to the SAVED view, not the
            // one being left (Codex P1.7). (Facets live in the query string, not
            // the hash, so they're unchanged across this hash-only nav.)
            const restoredAlt = s.alt != null ? s.alt : viewer.camera.positionCartographic.height;
            const target = computeTargetMode(restoredAlt, s.mode === 'point' ? 'point' : 'cluster');
            if (target === 'point') {
                if (getMode() !== 'point') await enterPointMode(false);
            } else {
                // Clusters at the restored altitude. Load FIRST (filter-aware), then
                // drop point mode only if it applied — no stale flash (P1.10) — and
                // re-check freshness after the await (P1.6).
                const res = restoredAlt > 3000000 ? 4 : restoredAlt > 300000 ? 6 : 8;
                const wasPoint = getMode() === 'point';
                const applied = await loadRes(res, { 4: h3_res4_url, 6: h3_res6_url, 8: h3_res8_url }[res]);
                if (isStale()) return;
                if (applied && wasPoint) 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];
                    const meta = {
                        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
                    };
                    updateSampleCard(meta);
                    // #285: also open the floating in-map card (parity with
                    // row-click). Camera already framed by the flyTo above.
                    await openInMapCardForSample(meta, isStale);
                } else {
                    // pid no longer resolves — clear any floating card left
                    // over from a prior pid selection (#285).
                    hideInMapCard();
                }
            } catch(err) {
                console.error("Hash pid query failed:", err);
            }
        } else if (state.h3) {
            viewer._globeState.selectedPid = null;
            viewer._globeState.selectedH3 = state.h3.toLowerCase();
            // #285: navigating to a cluster selection clears the sample-only
            // floating in-map card (mirrors the map cluster-click path).
            hideInMapCard();
            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 = '';
                // #172 Inc 1 (Codex round-2/round-5): list teardown → clear the pin
                // snapshot too AND advance _panelGen (unified rule).
                if (viewer.searchResultPoints) viewer.searchResultPoints.removeAll();
                viewer._panelGen++;
            }
        } else {
            viewer._globeState.selectedPid = null;
            viewer._globeState.selectedH3 = null;
            updateClusterCard(null);
            // #285: no selection in the new hash — clear the floating card too.
            hideInMapCard();
            const sampEl = document.getElementById('samplesSection');
            if (sampEl) sampEl.innerHTML = '';
            // #172 Inc 1 (Codex round-2/round-5): the Back-after-pin-click
            // no-selection branch tears down the preserved search list → clear its
            // pins too AND advance _panelGen (unified rule) so a slow in-flight
            // search can't resurrect the list after the user navigated away.
            if (viewer.searchResultPoints) viewer.searchResultPoints.removeAll();
            viewer._panelGen++;
        }
    });

    // --- Share button ---
    const shareBtn = document.getElementById('shareBtn');
    if (shareBtn) {
        shareBtn.addEventListener('click', async () => {
            writeGlobeHash(viewer, { force: true });
            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 (substrate index probe by default since the #172 flip; one
    // ILIKE scan over facets_url on the ?fts=off / PID-query interim path),
    // 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 scan 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 69 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 },
        ]);

        // #278/#26 — PID-aware search: when any term looks like a persistent
        // identifier (ARK, IGSN, DOI, resolver URL), OR a normalised PID
        // predicate into the WHERE so the sample is found even though its pid
        // doesn't appear in label/description/place_name. Plain-text terms
        // (e.g. "pottery") are unaffected — no pid column is touched for them,
        // preserving the existing hot-path performance.
        const pidPredicates = terms
            .filter(t => looksLikePid(t))
            .map(t => pidSearchWhere(t));
        // Combine: original text-field match OR any pid predicate.
        // If no terms look like PIDs, fullWhere equals searchWhere exactly.
        const fullWhere = pidPredicates.length
            ? `(${searchWhere} OR ${pidPredicates.join(' OR ')})`
            : searchWhere;

        // 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 ${fullWhere}
            `);
            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' };
            // #340: paint the unavailable dash the instant search goes active, and
            // invalidate any refresh that was scheduled while it was still inactive
            // (that one would otherwise fire mid-flight and re-enter the never-
            // settling search+bbox count path). See refreshFacetCounts().
            refreshFacetCounts();
            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 };
            refreshFacetCounts();   // #340: see buildSearchFilter / refreshFacetCounts()
            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 */ }
        }
    }

    // ===== #171: substrate search path (default; escape hatch ?fts=off) =====
    // Replaces buildSearchFilter's 69 MB facets ILIKE scan with the
    // sharded inverted index at data.isamples.org/isamples_202608_search_index_v1/
    // (built by tools/build_search_index.py, contract SEARCH_INDEX_V1.md).
    // Downstream shares one contract: both producers emit the singleton
    // `search_pids` table (pid, label, source, place_name, relevance_score);
    // the semi-join surfaces are common, with substrate-specific branches
    // where display columns arrive null (backfilled via samples_map_lite).
    // DEFAULT ON as of 2026-07-17 (#172 ship decision): the substrate wins
    // every benchmark row vs the interim path (e.g. no-hit 62.7s → 5.5s),
    // all hard-fail invariants pass, and a hand review of the benchmark
    // top-10s found no glaring ranking regressions. `?fts=off` reverts to
    // the interim ILIKE scan — kept intact as the rollback path and for
    // SME A/B ranking comparison (see #172); `?fts=v1` remains accepted so
    // pre-flip opt-in links behave identically. §7 end-to-end budgets stay
    // open in #172 as the pin-overlay / downstream-latency track.
    const SUBSTRATE_BASE = search_index_base;   // shared cell — see #334 manifest check
    let _substrateMeta = null;

    function substrateEnabled() {
        try {
            // getAll: `off` dominates even with duplicate params
            // (?fts=v1&fts=off) — a rollback switch must win ties.
            return !new URLSearchParams(location.search).getAll('fts').includes('off');
        } catch (e) { return true; }
    }

    async function loadSubstrateMeta() {
        // Three KB-scale sidecars, fetched once per session on FIRST substrate
        // search (deliberately NOT at boot — flag-off visitors pay nothing).
        if (_substrateMeta) return _substrateMeta;
        const [hot, sizes, stats] = await Promise.all([
            fetch(`${SUBSTRATE_BASE}/hot_tokens.json`).then(r => r.json()),
            fetch(`${SUBSTRATE_BASE}/shard_sizes.json`).then(r => r.json()),
            fetch(`${SUBSTRATE_BASE}/build_stats.json`).then(r => r.json()),
        ]);
        _substrateMeta = {
            manifest: { shardCount: stats.shard_count, hotTokens: hot.tokens },
            shardSizes: sizes,
            stats: {
                totalDocs: stats.total_documents,
                avgDocLenByField: Object.fromEntries(
                    Object.entries(stats.fields).map(([f, v]) => [f, v.avg_doc_len])),
            },
        };
        return _substrateMeta;
    }

    let _substrateModPromise = null;

    async function buildSearchFilterSubstrate(term) {
        const token = ++_searchFilterToken;
        window.a1dbg?.('substrate-search-start', { term, token });
        // Lazy module import (Codex review): ?fts=off visitors must not
        // download/evaluate the substrate modules, and a module-load failure
        // must not be able to kill the search cell — so the import happens
        // HERE, on first substrate search, not as an OJS dependency. A
        // REJECTED import resets the cache so the next search retries
        // instead of failing forever on one transient network hiccup
        // (Codex P2 on PR #335 — matters now that substrate is the default).
        _substrateModPromise ??= import(new URL('assets/js/search_substrate.js', document.baseURI).href)
            .catch(e => { _substrateModPromise = null; throw e; });
        const _searchSubstrate = await _substrateModPromise;
        if (token !== _searchFilterToken) return false;   // superseded during import
        const meta = await loadSubstrateMeta();
        if (token !== _searchFilterToken) return false;   // superseded during meta fetch
        const plan = _searchSubstrate.planQuery(term, meta.manifest, meta.shardSizes);
        if (plan.mode === 'empty' || plan.mode === 'allStopwords') {
            // Controlled empty per contract §3 — never a corpus dump.
            await clearSearchFilter();
            window.__searchFilter = {
                active: false, term: null, token: _searchFilterToken, total: 0,
                kind: 'text', substrate: true,
                note: plan.mode === 'allStopwords'
                    ? 'All terms in your query are common words. Add a more specific term to search.'
                    : null,
            };
            return false;
        }
        // Tokens are lowercase alphanumeric BY TOKENIZER CONSTRUCTION (see
        // search_tokenizer §4: every non-\p{L}\p{N} char became a separator),
        // so interpolating them into SQL string literals cannot break out.
        const tokList = plan.tokens.map(t => `'${t}'`).join(',');
        const stats = meta.stats;
        const staging = `search_pids_next_${token}`;
        try {
            if (plan.mode === 'topk') {
                // All surviving terms are common: intersect the precomputed
                // per-token top-500 lists, sum static scores (§6 —
                // documented approximation, benchmarked at #172).
                await db.query(`
                    CREATE OR REPLACE TABLE ${staging} AS
                    WITH agg AS (
                        SELECT pid, sum(static_score) AS relevance_score,
                               count(DISTINCT token) AS m
                        FROM read_parquet('${SUBSTRATE_BASE}/hot_topk.parquet')
                        WHERE token IN (${tokList})
                        GROUP BY pid
                    )
                    SELECT a.pid,
                           NULL::VARCHAR AS label, NULL::VARCHAR AS source,
                           NULL::VARCHAR AS place_name,
                           a.relevance_score
                    FROM agg a
                    WHERE a.m = ${plan.tokens.length}
                `);
            } else {
                const urls = plan.files.map(f => `'${SUBSTRATE_BASE}/${f}'`).join(',');
                const avgCase = Object.entries(stats.avgDocLenByField)
                    .map(([f, v]) => `WHEN '${f}' THEN ${Number(v)}`).join(' ');
                // BM25 per contract §5 — identical constants/shape to the
                // builder's hot_topk scoring and the JS module's
                // bm25Contribution (which unit-tests pin). df is EMBEDDED in
                // the shard rows (round-5 amendment) — no df.parquet fetch.
                await db.query(`
                    CREATE OR REPLACE TABLE ${staging} AS
                    WITH hits AS (
                        SELECT token, pid, field, tf, doc_len, df
                        FROM read_parquet([${urls}])
                        WHERE token IN (${tokList})
                    ), contrib AS (
                        SELECT token, pid,
                            (CASE field
                                WHEN 'sample.label' THEN 3.0
                                WHEN 'concept.label' THEN 2.5
                                WHEN 'sample.place_name' THEN 2.0
                                ELSE 1.0 END)
                            * ln(((${stats.totalDocs} - df + 0.5) / (df + 0.5)) + 1)
                            * (tf * 2.2) / (tf + 1.2 * (0.25 + 0.75 * doc_len /
                                (CASE field ${avgCase} ELSE 10.0 END))) AS c
                        FROM hits
                    ), agg AS (
                        SELECT pid, sum(c) AS relevance_score,
                               count(DISTINCT token) AS m
                        FROM contrib GROUP BY pid
                    )
                    SELECT a.pid,
                           NULL::VARCHAR AS label, NULL::VARCHAR AS source,
                           NULL::VARCHAR AS place_name,
                           a.relevance_score
                    FROM agg a
                    WHERE a.m = ${plan.tokens.length}
                `);
            }
            if (token !== _searchFilterToken) return false;   // superseded
            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', substrate: true,
                substrateMode: plan.mode,
                ignoredCommon: plan.ignoredCommon,
                expectedBytes: plan.expectedBytes,
            };
            refreshFacetCounts();   // #340: see buildSearchFilter / refreshFacetCounts()
            window.a1dbg?.('substrate-search-end',
                { term, token, total, mode: plan.mode, ignored: plan.ignoredCommon });
            return true;
        } finally {
            try { await db.query(`DROP TABLE IF EXISTS ${staging}`); } catch (e) { /* best effort */ }
        }
    }
    // ===== end #171 substrate path =====

    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++;
        // #172 Inc 1 (Codex round-3 P1): take panel ownership so an in-flight
        // selection hydration can't repopulate the list after this clear.
        freshSelectionToken(viewer);
        // #172 pin-overlay Inc 1 (option C / round-5 unified rule): the committed
        // concept-chip clear tears down the results list, so clear the LIST and the
        // pin overlay TOGETHER and advance _panelGen so an in-flight async producer
        // (search / hydration) can't resurrect the list after this clear.
        if (viewer.searchResultPoints) viewer.searchResultPoints.removeAll();
        viewer._panelGen++;
        const sampElClear = document.getElementById('samplesSection');
        if (sampElClear) sampElClear.innerHTML = '';
        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();
    }

    // #172 pin-overlay Inc 1 (option C): shared selection ceremony for a search
    // result, invoked by BOTH the side-panel row click (in doSearch) and the
    // on-globe result-pin click (viewer cell, via viewer.selectSearchResult).
    // Mirrors the on-globe sample-click ceremony — freshness token, card
    // hydration, selection state, flight, lazy detail — but deliberately does
    // NOT repaint #samplesSection (it holds the search-results list the user is
    // browsing). `sample` is a normalized meta ({ pid, label, source, lat, lng,
    // place_name, result_time }); coord-less rows are ignored.
    //
    // `inMapCardAt` (pin click only): open the floating in-map card at the click
    // pixel with the SAME rich detail (material / feature / specimen / thumbnail)
    // the sample click renders — via the shared openInMapCardForSample(), so the
    // wide-table fetch is reused, not duplicated (Codex round-1 P1.3).
    //
    // `isStale` (Codex round-1 P1.3): callers that already bumped the freshness
    // token (the globe click handler) pass theirs so we don't double-bump; the
    // row click passes none and we bump here.
    async function selectSearchResult(sample, { fly = true, inMapCardAt = null, isStale = null } = {}) {
        if (!sample || sample.lat == null || sample.lng == 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.
        if (!isStale) isStale = freshSelectionToken(viewer);

        viewer._globeState.selectedPid = sample.pid;
        viewer._globeState.selectedH3 = null;
        updateSampleCard(sample);
        if (fly) {
            viewer.camera.flyTo({
                destination: Cesium.Cartesian3.fromDegrees(sample.lng, sample.lat, 50000),
                duration: 1.5
            });
        }

        if (inMapCardAt) {
            // Pin click: full in-map card hydration at the click pixel, reusing
            // the shared wide-table fetch (updateSampleDetail +
            // populateInMapCardDetail happen inside).
            await openInMapCardForSample(sample, isStale, inMapCardAt);
            return;
        }

        // Row click: sidebar description only (no in-map card). Don't clear
        // samplesSection — it holds the results the user is browsing.
        try {
            const detail = await db.query(`
                SELECT description
                FROM read_parquet('${wide_url}')
                WHERE pid = '${sample.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-result detail query failed:", err);
            updateSampleDetail(null);
        }
    }
    // Expose for the viewer cell's globe click handler (result-pin click).
    viewer.selectSearchResult = selectSearchResult;

    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;

        // #172 Inc 1: take PANEL OWNERSHIP two ways.
        // (round-3, _selGen) bump the selection freshness token so in-flight
        // sample/pid detail + cluster hydrations become stale and bail — this
        // guards selection/card work.
        freshSelectionToken(viewer);
        // (round-4/round-5, _panelGen) this submit is a write to the panel list,
        // so advance _panelGen AND capture it — one bump serves both. As a bump it
        // invalidates any in-flight async producer (unified rule); as this search's
        // captured generation it is re-checked (with _searchSeq) before every
        // render below, so a newer list producer that starts AFTER this submit
        // (e.g. a cluster click while the search is still building) makes this
        // render bail instead of overwriting the cluster's rows. Does NOT break
        // boot search+pid: the pid deep-link is card-only and never bumps.
        const myPanelGen = ++viewer._panelGen;

        // #172 Inc 1 (Codex round-5 P1.2): a new submit tears the panel DOWN.
        // Clear the old rows AND pins together AT ENTRY (under the gen just
        // captured), so no stale unpinned rows linger during the async build — the
        // panel shows the building status (searchResults text) until the atomic
        // replacement lands. This covers BOTH the committed real search below and
        // the empty/too-short branch (which just leaves the panel cleared).
        if (viewer.searchResultPoints) viewer.searchResultPoints.removeAll();
        const sampElEntry = document.getElementById('samplesSection');
        if (sampElEntry) sampElEntry.innerHTML = '';

        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) => {
            // #171 disclosure (contract §3/§6): when the substrate path
            // dropped common terms from the AND, the user must see exactly
            // which words were ignored — silent semantic change is the one
            // thing the policy forbids.
            const sf = (typeof window !== 'undefined') ? window.__searchFilter : null;
            const ignored = (sf && sf.substrate && sf.ignoredCommon && sf.ignoredCommon.length)
                ? `<div style="font-size: 11px; font-weight: normal; margin-top: 2px;">Very common word${sf.ignoredCommon.length > 1 ? 's' : ''} ignored: ${sf.ignoredCommon.map(escapeHtml).join(', ')}</div>`
                : '';
            return `<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}${ignored}</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. On the interim path (?fts=off / PID queries) the ILIKE
        // scan warms the text columns in the DuckDB buffer; the substrate
        // default probes the sharded index instead and touches no facets
        // columns. 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 {
            // #171/#172: the sharded-substrate path is the default; ?fts=off
            // reverts to the interim scan. Both producers emit the identical
            // `search_pids` singleton, so everything downstream is shared.
            // PID-looking queries (ARK / IGSN / DOI / resolver URL / pid:)
            // always take the interim builder: the substrate index carries
            // only text fields (SEARCH_INDEX_V1 §2 — label/description/place/
            // concept labels), so tokenizing a pasted identifier would return
            // zero or unrelated matches. The interim path has the exact-PID
            // arm (#278/#26). Rare query class — paying its cold cost beats
            // silently wrong results. (Codex P1 on PR #335.)
            if (substrateEnabled() && !terms.some(t => looksLikePid(t))) {
                await buildSearchFilterSubstrate(term);
            } else {
                await buildSearchFilter(terms, term);
            }
        } catch (e) {
            console.warn('A1 search-filter build failed; surfaces stay unfiltered:', e);
            searchFilterBuildFailed = true;
            // Guard the clear (Codex review of #171): an error inside a
            // SUPERSEDED search's build must not blow away the newer
            // search's freshly-built filter. Applies to both paths.
            if (searchId === _searchSeq) 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. #171 HAS landed and is the default (#172 flip,
            // 2026-07-17): this interim builder now serves ?fts=off rollback
            // and PID-looking queries (exact-PID arm — the substrate index
            // has no PID field), so it stays until the substrate grows one.
            //
            // 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 69 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.
            // #171 perf fix: the substrate builder no longer joins lite at
            // filter-build time (the 42k-row remote join made big-result
            // queries SLOWER than baseline — benchmark 2026-07-11, Codex-
            // verified). search_pids now carries NULL display columns for
            // substrate searches, so every consumer below joins lite and
            // filters on the COALESCEd value (interim rows still carry
            // their own values; NULL-vs-value never changes interim
            // semantics because COALESCE prefers s.*).
            const sourceSQL = sourceFilterSQL("COALESCE(s.source, l.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,
                               COALESCE(s.label, l.label) AS label,
                               COALESCE(s.source, l.source) AS source,
                               l.latitude, l.longitude,
                               COALESCE(s.place_name, CAST(l.place_name AS VARCHAR)) AS 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, COALESCE(s.label, l.label)
                        LIMIT 50
                    `);
                    effectiveQueryShape = 'area';
                    effectiveBboxSQL = bboxSQL;
                }
            } else {
                results = await runWorldQuery();
            }

            async function runWorldQuery() {
                return db.query(`
                    ${
                        // Codex review (lite-join deferral, round 2): the
                        // join-everything-then-filter shape is ONLY needed
                        // when substrate rows (NULL s.source) must satisfy an
                        // ACTIVE source filter that reads l.source. In every
                        // other case — the interim producer, or no source
                        // filter — keep the original cheap shape: filter +
                        // LIMIT 50 first, join lite for just those 50.
                        (window.__searchFilter?.substrate && sourceSQL !== '')
                        ? `
                    SELECT s.pid,
                           COALESCE(s.label, l.label) AS label,
                           COALESCE(s.source, l.source) AS source,
                           l.latitude, l.longitude,
                           COALESCE(s.place_name, CAST(l.place_name AS VARCHAR)) AS place_name,
                           s.relevance_score
                    FROM search_pids s
                    LEFT JOIN read_parquet('${lite_url}') l USING (pid)
                    WHERE 1=1
                    ${sourceSQL}
                    ${facetSQL}
                    ORDER BY s.relevance_score DESC, COALESCE(s.label, l.label)
                    LIMIT 50`
                        : `
                    WITH matches AS (
                        SELECT s.pid, s.label, s.source, s.place_name,
                               s.relevance_score
                        FROM search_pids s
                        WHERE 1=1
                        ${facetSQL}
                        ${window.__searchFilter?.substrate ? '' : sourceSQL.replaceAll('COALESCE(s.source, l.source)', 's.source')}
                        ORDER BY s.relevance_score DESC
                        LIMIT 50
                    )
                    SELECT m.pid,
                           COALESCE(m.label, l.label) AS label,
                           COALESCE(m.source, l.source) AS source,
                           l.latitude, l.longitude,
                           COALESCE(m.place_name, CAST(l.place_name AS VARCHAR)) AS place_name,
                           m.relevance_score
                    FROM matches m
                    LEFT JOIN read_parquet('${lite_url}') l USING (pid)
                    ORDER BY m.relevance_score DESC, COALESCE(m.label, l.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;
            }
            // #172 Inc 1 (Codex round-4 P1): also bail if a newer LIST producer
            // (e.g. a cluster click while this search was building) took the
            // panel. Both _searchSeq (search supersession) and _panelGen (list
            // ownership) must hold before we write the list/pins — there is no
            // await between here and the row-render + pin-populate below, so this
            // single check makes that write atomic w.r.t. panel ownership.
            if (!panelWriteAllowed(myPanelGen, viewer._panelGen)) {
                wasSuperseded = true;
                // #172 Inc 1 (Codex round-5 P2): panel ownership and search-status
                // completion are separate. A cluster took the panel, so we won't
                // render — but if no NEWER search owns the status text (our
                // searchId still current), settle our own "Searching…" to '' so it
                // can't persist forever. If a newer search owns the text, leave it.
                if (searchId === _searchSeq) searchResults.textContent = '';
                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 —
                // and (#171, Codex review) a substrate controlled-empty state
                // (all-stopword query) must show ITS copy, not a generic
                // "No results": the message tells the user what to do.
                const substrateNote = (window.__searchFilter?.substrate && window.__searchFilter?.note)
                    ? window.__searchFilter.note : null;
                searchResults.textContent = searchFilterBuildFailed
                    ? `Search error: couldn't build the filter for "${term}". Please try again.`
                    : (substrateNote || `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.' : escapeHtml(substrateNote || '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;
            // #172 pin-overlay Inc 1 (option C): one pin per LOCATED displayed
            // result (world scope legitimately returns coord-less matches). When
            // fewer results are located than displayed, the count line discloses
            // how many landed on the globe. Cap is inherited from LIMIT 50, so
            // located ≤ displayed ≤ 50.
            const locatedCount = results.filter(r => r.latitude != null && r.longitude != null).length;
            const pinnedNote = locatedCount < results.length
                ? ` (${locatedCount} located, pinned on globe)`
                : '';
            searchResults.textContent = (capReached
                ? `${results.length}+ results for "${term}"`
                : `${results.length} results for "${term}"`) + pinnedNote;

            // 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.
                // #172 pin-overlay Inc 1 (option C): that ceremony now lives in
                // the shared selectSearchResult() helper, used by BOTH this row
                // click and the on-globe result-pin click. Row click keeps its
                // prior behavior (no in-map card, no selection-hash write).
                const resultsByPid = new Map(results.map(s => [s.pid, s]));
                sampEl.querySelectorAll('.sample-row[data-lat]').forEach(row => {
                    row.addEventListener('click', (e) => {
                        if (e.target.tagName === 'A') return; // let links work
                        const pid = row.dataset.pid;
                        const s = pid ? resultsByPid.get(pid) : null;
                        if (!s) return;
                        selectSearchResult({
                            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
                        }, { fly: true });
                    });
                });
            }

            // #172 pin-overlay Inc 1 (option C): render the LOCATED displayed
            // results as a pin overlay on the globe. One hollow-ring pin per
            // located row — skip null lat/lng (world scope legitimately returns
            // coordinate-less matches; NEVER coerce to (0,0)). Old pins were
            // cleared at the top of doSearch (committed-clear path); the cap is
            // inherited from LIMIT 50, so pins ≤ 50 ≤ displayed results.
            //
            // LIFECYCLE POLICY (snapshot semantics, Codex round-1 P1.2): the
            // pins are a snapshot of the rendered results list — they reconcile
            // with the LIST lifecycle, not with filter state. They are cleared
            // wherever that list is torn down (new/empty submit, described-by
            // takeover, and the globe sample/cluster clicks that replace the
            // list). They deliberately PERSIST when the list persists stale —
            // e.g. a source/facet toggle while a search is active updates the
            // #300 filtered surfaces but not the (frozen) results list, so the
            // pins stay too. That staleness is the documented pre-existing
            // behavior of the list itself, not a new pin bug.
            const pinScalar = new Cesium.NearFarScalar(1e2, 8, 2e5, 3);  // mirror samplePoints
            for (const s of results) {
                if (s.latitude == null || s.longitude == null) continue;
                const c = SOURCE_COLORS[s.source] || '#666';
                viewer.searchResultPoints.add({
                    id: {
                        type: 'searchResult',
                        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
                    },
                    position: Cesium.Cartesian3.fromDegrees(s.longitude, s.latitude, 0),
                    pixelSize: 8,
                    // Hollow ring: faint fill + bright source-colored outline so
                    // the overlay reads as distinct from the filled cluster and
                    // sample dots while still signalling which source matched.
                    color: Cesium.Color.fromCssColorString(c).withAlpha(0.15),
                    outlineColor: Cesium.Color.fromCssColorString(c),
                    outlineWidth: 2,
                    scaleByDistance: pinScalar,
                    // #185 (Codex round-1 P1.1): bounded depth-test distance —
                    // Number.POSITIVE_INFINITY bleeds pins through the far side
                    // of the globe; POINT_DEPTH_TEST_DISTANCE matches the h3/
                    // sample layers and prevents that back-hemisphere bleed.
                    disableDepthTestDistance: POINT_DEPTH_TEST_DISTANCE,
                });
            }

            // Fly to the first LOCATED 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.
            //
            // #172 Inc 1 (Codex round-1 P1.5): scan for the first row with
            // real coordinates using EXPLICIT null checks (0° lat/lng is
            // valid). results[0] can be coord-less in world scope (LEFT JOIN
            // to lite), so the old truthiness test on results[0] both skipped
            // the flight for a coord-less top row and would have mis-treated
            // 0,0. Fit-to-bounds (the 30°×30° camera rule) remains deferred to
            // Inc 2 per PLAN_PIN_OVERLAY_2026-07-17.md.
            const firstLocated = results.find(r => r.latitude != null && r.longitude != null);
            if (effectiveScope === 'world' && firstLocated) {
                const cancelFinalFacetRefresh = refreshFacetCountsAfterSearchFlight(searchId);
                viewer._globeState.selectedPid = null;
                viewer._globeState.selectedH3 = null;
                viewer.camera.flyTo({
                    destination: Cesium.Cartesian3.fromDegrees(firstLocated.longitude, firstLocated.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
                        LEFT JOIN read_parquet('${lite_url}') l USING (pid)
                        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.
                    // #172: preserve the located/pinned disclosure across the
                    // real-count follow-up (pinnedNote is captured above).
                    searchResults.textContent = (total > results.length
                        ? `${results.length} of ${total.toLocaleString()} results for "${term}"`
                        : `${results.length} results for "${term}"`) + pinnedNote;
                } 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.
                // #172 Inc 1 (Codex round-4 P1): but only if we still own the
                // panel — a newer list producer must not have its rows replaced
                // by this (older) search's failure message.
                if (panelWriteAllowed(myPanelGen, viewer._panelGen)) {
                    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;

        // #172 Inc 1: take PANEL OWNERSHIP — same as doSearch. (round-3, _selGen)
        // bump the selection token so in-flight selection hydrations bail; (round-4/
        // round-5, _panelGen) advance + capture a LIST generation — as a bump it
        // invalidates in-flight async producers (unified rule); as this concept's
        // gen it's re-checked before every render, so a cluster click that starts
        // AFTER this commit wins the list. The render also stays guarded by
        // searchId/_searchSeq.
        freshSelectionToken(viewer);
        const myPanelGen = ++viewer._panelGen;

        // #172 Inc 1 (Codex round-5 P1.2): committing a concept tears the panel
        // DOWN — clear the old rows AND the text-search pins together at entry
        // (the panel shows "Filtering by concept…" until the concept list lands).
        if (viewer.searchResultPoints) viewer.searchResultPoints.removeAll();
        const sampElEntry = document.getElementById('samplesSection');
        if (sampElEntry) sampElEntry.innerHTML = '';

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

        // #172 Inc 1 (Codex round-4 P1): a newer list producer (cluster click)
        // may own the panel now — gate the failed/empty LIST renders on it (the
        // URL write above stays _searchSeq's concern).
        const conceptOwnsPanel = () => panelWriteAllowed(myPanelGen, viewer._panelGen);
        if (buildFailed) {
            if (searchResults) searchResults.textContent = `Concept filter failed for "${label}". Please try again.`;
            if (!conceptOwnsPanel()) return;
            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}"`;
            if (!conceptOwnsPanel()) return;
            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}"`;

        // #172 Inc 1 (Codex round-4 P1): bail if a newer list producer took the
        // panel while this concept query was in flight.
        if (!conceptOwnsPanel()) return;
        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];
                    const meta = {
                        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
                    };
                    updateSampleCard(meta);
                    // #285: open the floating in-map card too (parity with
                    // row-click), not just the sidebar. The shared helper runs
                    // the richer detail query (material/specimen/thumbnail) that
                    // supersedes the old description-only sidebar query, and
                    // anchors the card at canvas centre where the URL-hydrated
                    // camera frames the sample.
                    await openInMapCardForSample(meta, isStale);
                    // The helper awaits a remote query; if a hashchange
                    // superseded this boot lookup meanwhile, abort the rest of
                    // the boot deep-link hydration (mode/heatmap below) just as
                    // the old description-only query did.
                    if (isStale()) return "active";
                }
            } 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.
    // #300: resolve the boot mode through computeTargetMode so a cold boot with a
    // facet active behaves like the live/hashchange paths — point below EXIT
    // (or whenever filtered clusters aren't ready), FILTERED clusters above.
    // The latch is the saved hash mode (point explicit, cluster by omission), so
    // the hysteresis band restores the saved view (Codex P1.7). This still enters
    // point for the #203 loophole (alt < ENTER without mode=point → point).
    const bootAlt = ih.alt != null ? ih.alt : viewer.camera.positionCartographic.height;
    const bootTarget = computeTargetMode(bootAlt, ih.mode === 'point' ? 'point' : 'cluster');
    if (bootTarget === 'point') {
        if (getMode() !== 'point') {
            // tryEnterPointModeIfNeeded() refuses at alt >= ENTER_POINT_ALT, so it
            // can't restore an explicit saved point view in the hysteresis band,
            // nor force point for a high-altitude facet/search when filtered
            // clusters aren't available. Enter directly for those forced/saved
            // cases; reserve the gentle helper (cold-cache messaging) for pure
            // altitude-driven entry below ENTER (Codex round-2 P1.5).
            if (searchIsActive() || hasFacetFilters() || ih.mode === 'point') {
                await enterPointMode(false);  // pushHistory:false (#207 item 3)
            } else {
                await tryEnterPointModeIfNeeded({ pushHistory: false });
            }
        }
    } else if (wantFilteredClusters() && viewer._clusterFilterSig !== desiredClusterSig()) {
        // phase1 loaded UNFILTERED summary clusters, but a facet is active at
        // cluster altitude — reload the FILTERED clusters so the cold-boot world
        // view matches the filter (Codex P1.7).
        const bootRes = bootAlt > 3000000 ? 4 : bootAlt > 300000 ? 6 : 8;
        await loadRes(bootRes, { 4: h3_res4_url, 6: h3_res6_url, 8: h3_res8_url }[bootRes]);
    }

    // #300: the dedicated `?material=`/`?context=`/`?object_type=` boot
    // force-point block was removed here — computeTargetMode() (driven above
    // through `bootTarget`) now owns the facet boot decision: point below EXIT
    // (or when filtered clusters aren't ready), FILTERED clusters above. Keeping
    // the old unconditional enterPointMode() would immediately undo the
    // filtered-cluster boot load (Codex round-2 P0).

    // #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";
}

// === 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";
}

1 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	0.5 MB	38K clusters (continental)
Zoom in	H3 res6	1.3 MB	112K clusters (city)
Zoom more	H3 res8	2.0 MB	176K clusters (neighborhood)
Zoom deep	Map lite	63 MB (range req.)	Up to 5K individual samples
Click sample	Full dataset	300 MB (range req.)	Full metadata for 1 sample

Sizes are decimal MB (10⁶ bytes), matching the manifest’s byte counts.

Static files, zero backend. All queries run in your browser via DuckDB-WASM with HTTP range requests — only the bytes you need are transferred. The manifest directly inventories 21 objects — including five search-index sidecars — and summarizes the index’s 847 shard files (256 base plus 591 hot); the index directory holds 852 objects in all. Any one view touches only a handful of them. The authoritative inventory is isamples_202608_release_manifest.json (human twin: CANONICAL.md), which the Explorer cross-checks at boot.

TipCheck these numbers against the source

Every file-size figure above comes from the published release manifest, which the Explorer also cross-checks at boot. (The cluster counts come from the parquet row counts — see below — and the timings, the 120 km threshold and the 5K point budget are properties of the app, not the data.) To re-derive the sizes without taking this page’s word for it:

curl -s https://data.isamples.org/isamples_202608_release_manifest.json \
  | jq '.files | to_entries[] | select(.key|test("h3_summary|_wide\\.|map_lite"))
        | {file: .key, bytes: .value.size_bytes}'

Cluster counts come from the parquet row counts, not the manifest:

SELECT count(*) FROM read_parquet(
  'https://data.isamples.org/isamples_202608_h3_summary_res4.parquet');

2 See Also

• Guided Tour — seven views of the Explorer, with the queries behind them
• Tutorials — index of all interactive tutorials