topic layout: drop right rail — Contents + Open questions as collapsibles at top, Open questions + Sources-cited references at bottom; add figure/SVG rendering support

app.js

@@ -26,8 +26,10 @@ const state = {
   collapsed: new Set(JSON.parse(localStorage.getItem('viz-collapsed') || '[]')),
   treeCollapsed: new Set(JSON.parse(localStorage.getItem('viz-tree-collapsed') || '[]')),
   srcNs: null,        // selected source-namespace filter (null = all)
+  palItems: [],       // command-palette index
+  palFiltered: [],
+  palSel: 0,
   pageContent: new Map(),   // path -> article markdown (cached)
-  searchText: new Map(),    // topic path -> lowercased body, for nav content search
   citedBy: new Map(),       // sourceId -> Set(topic path) that cite it
   citeCount: new Map(),     // sourceId -> # distinct articles citing it
   wordCount: new Map(),     // topic path -> prose word count
@@ -190,29 +192,6 @@ function setupMarked() {
       renderer(tok) { return citationHTML(tok.id); },
     }],
   });
-  // Cross-references between topics are authored as bare `category/node` code
-  // spans (e.g. `preference-data/ai-feedback-data`) rather than markdown links.
-  // Turn each into a live hop to that topic — but only when the page exists, so
-  // genuine code spans (`preference/DPO`, planned-but-unwritten nodes) stay plain.
-  // (Markdown-link cross-refs are handled separately by rewriteInternalLinks;
-  // this href is already a `#/` route, so that pass leaves it untouched.)
-  marked.use({
-    renderer: {
-      // marked@13 hands codespan the already-HTML-escaped code text as a plain
-      // string (the {text} token arg is a marked-v16 API) — so read it directly
-      // and don't re-escape, or every cross-ref silently falls through to plain.
-      codespan(code) {
-        const m = /^([a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*)$/.exec(code);
-        if (m) {
-          const path = `topics/${m[1]}.md`;
-          if (state.pages.some(p => p.path === path)) {
-            return `<a class="xref" href="#/topic/${encodeURIComponent(path)}" title="Topic: ${m[1]}"><code>${code}</code></a>`;
-          }
-        }
-        return false;   // fall back to marked's default code-span rendering
-      },
-    },
-  });
   marked.setOptions({ gfm: true, breaks: false });
 }
 
@@ -290,56 +269,36 @@ function enhanceProse(root, currentPath) {
     if (h.tagName !== 'H4') toc.push({ slug, text: txt, level: h.tagName === 'H2' ? 2 : 3 });
   });
   if (window.hljs) $$('pre code', root).forEach(c => { try { hljs.highlightElement(c); } catch (e) {} });
+  wrapFigures(root);                         // images / inline SVG → captioned <figure>
   rewriteInternalLinks(root, currentPath);   // markdown links to topics/sources → in-app routes
   linkifySectionRefs(root, secMap);          // §N / §N.M → jump to that section
   acronymHovers(root);                       // known acronyms get a hover definition
   // remaining external links open in a new tab
   $$('a[href^="http"]', root).forEach(a => { a.target = '_blank'; a.rel = 'noopener'; });
-  highlightDocMatches(root, ($('#navSearch') || {}).value);   // mark active search terms in the article
   return toc;
 }
-
-// In-document search highlighting: <mark> occurrences of the active query in the
-// rendered article. Cleared when the search is cleared (see clearNavSearch).
-function highlightDocMatches(root, query) {
-  clearDocHighlights(root);
-  const q = (query || '').trim().toLowerCase();
-  if (!root || q.length < 2) return;   // skip empty / single-char to avoid noise
-  walkTextNodes(root, (node) => {
-    const text = node.nodeValue, lc = text.toLowerCase();
-    let idx = lc.indexOf(q);
-    if (idx < 0) return;
-    const frag = document.createDocumentFragment();
-    let last = 0;
-    while (idx >= 0) {
-      if (idx > last) frag.append(text.slice(last, idx));
-      const mark = document.createElement('mark');
-      mark.className = 'search-hl';
-      mark.textContent = text.slice(idx, idx + q.length);
-      frag.append(mark);
-      last = idx + q.length;
-      idx = lc.indexOf(q, last);
-    }
-    if (last < text.length) frag.append(text.slice(last));
-    node.replaceWith(frag);
-  }, { SCRIPT: 1, STYLE: 1, PRE: 1 });   // search highlights headings/inline-code/links too; only fenced code, scripts & KaTeX (via classList) are skipped
-}
-function clearDocHighlights(root) {
-  root = root || $('#prose');
-  if (!root) return;
-  const marks = root.querySelectorAll('mark.search-hl');
-  marks.forEach(m => m.replaceWith(document.createTextNode(m.textContent)));
-  if (marks.length) root.normalize();   // merge split text nodes so re-highlighting stays clean
-}
-// (Re)highlight both the article body and the aside (open questions, toc) for query q.
-function refreshDocHighlights(q) {
-  highlightDocMatches($('#prose'), q);
-  highlightDocMatches($('#aside'), q);
+// Present visuals as proper figures: a markdown image (alt → caption) or a
+// block-level inline <svg> becomes a centered <figure> with an optional caption.
+function wrapFigures(root) {
+  $$('img', root).forEach(img => {
+    if (img.closest('figure')) return;
+    const fig = el('figure', 'fig');
+    img.replaceWith(fig); fig.append(img);
+    const cap = img.getAttribute('alt');
+    if (cap) fig.append(el('figcaption', null, esc(cap)));
+    img.loading = 'lazy';
+  });
+  $$(':scope > svg, :scope > p > svg', root).forEach(svg => {
+    const host = svg.parentElement.tagName === 'P' ? svg.parentElement : svg;
+    if (host.closest && host.closest('figure')) return;
+    const fig = el('figure', 'fig');
+    host.replaceWith(fig); fig.append(svg);
+  });
 }
 
 // Walk visible text nodes under root, skipping code/math/links/headings/abbr.
-function walkTextNodes(root, fn, skip) {
-  const SKIP = skip || { CODE: 1, PRE: 1, A: 1, ABBR: 1, SCRIPT: 1, STYLE: 1, H1: 1, H2: 1, H3: 1, H4: 1, H5: 1, H6: 1 };
+function walkTextNodes(root, fn) {
+  const SKIP = { CODE: 1, PRE: 1, A: 1, ABBR: 1, SCRIPT: 1, STYLE: 1, H1: 1, H2: 1, H3: 1, H4: 1, H5: 1, H6: 1 };
   const w = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
     acceptNode(n) {
       if (!n.nodeValue.trim()) return NodeFilter.FILTER_REJECT;
@@ -500,7 +459,7 @@ async function softRefresh() {
    ============================================================ */
 function layoutAside(on) { $('#layout').classList.toggle('has-aside', !!on); }
 function setView(html) { $('#view').innerHTML = html; }
-function setAside(html) { $('#aside').innerHTML = html || ''; highlightDocMatches($('#aside'), ($('#navSearch') || {}).value); }
+function setAside(html) { $('#aside').innerHTML = html || ''; }
 function showError(msg) {
   layoutAside(false);
   setView(`<div class="error-box">⚠ ${esc(msg)}<br><br><a class="btn" href="#/">← back to home</a></div>`);
@@ -751,43 +710,68 @@ async function renderTopic(path) {
   const title = fm.title || meta.title || path.split('/').pop().replace(/\.md$/, '');
   const cat = meta.parent || path.split('/').slice(-2, -1)[0] || '';
 
-  layoutAside(true);
+  layoutAside(false);   // no right rail — single reading column
   setView(`
-    <div class="crumbs"><a href="#/">Wiki</a><span class="sep">/</span>
-      <span>${esc(catDisplay(cat))}</span></div>
-    <div class="doc-head">
-      <div class="doc-kicker">Topic Article<button class="share-btn" data-share title="Copy a link to this page">🔗 copy link</button></div>
-      <h1 class="doc-title">${esc(title)}</h1>
-      <div class="doc-meta-row">
-        ${maturityBadge(fm.maturity)}
-        ${fm.sources ? `<span class="doc-sub">${fm.sources.length} source${fm.sources.length === 1 ? '' : 's'} cited</span>` : ''}
+    <div class="doc">
+      <div class="crumbs"><a href="#/">Wiki</a><span class="sep">/</span>
+        <span>${esc(catDisplay(cat))}</span></div>
+      <div class="doc-head">
+        <div class="doc-kicker">Topic Article<button class="share-btn" data-share title="Copy a link to this page">🔗 copy link</button></div>
+        <h1 class="doc-title">${esc(title)}</h1>
+        <div class="doc-meta-row">${maturityBadge(fm.maturity)}</div>
       </div>
+      <div id="docTop"></div>
+      <div class="prose" id="prose">${renderBody(body)}</div>
+      <div id="docBottom"></div>
+      ${footerHTML()}
     </div>
-    <div class="prose" id="prose">${renderBody(body)}</div>
-    ${footerHTML()}
   `);
   wireShare();
   const toc = enhanceProse($('#prose'), path);
   bindInternalLinks($('#prose'));
 
-  // Aside: cited sources, open questions, TOC, links
-  let aside = '';
-  if (fm.sources?.length) {
-    aside += `<div class="panel"><div class="panel-title">Cited sources</div><div class="chips">` +
-      fm.sources.map(id => sourceChip(id)).join('') + `</div></div>`;
-  }
-  if (fm.open_questions?.length) {
-    aside += `<div class="panel"><div class="panel-title">Open questions</div><ul class="oq-list">` +
-      fm.open_questions.map(q => `<li>${renderInline(q)}</li>`).join('') + `</ul></div>`;
-  }
-  aside += tocPanel(toc);
-  aside += `<div class="panel"><div class="panel-title">This page</div>
-    <div class="chips">
-      <a class="chip ext" href="${esc(RESOLVE)}/${esc(path)}" target="_blank" rel="noopener">raw .md</a>
-      <a class="chip ext" href="${esc(DATASET_BLOB)}/${esc(path)}" target="_blank" rel="noopener">on HF</a>
-    </div></div>`;
-  setAside(aside);
-  initScrollSpy(toc);
+  // cited sources, in the order they first appear in the article
+  const citedIds = []; const seenCite = new Set();
+  $$('#prose .cite[data-src]').forEach(a => { const id = a.dataset.src; if (!seenCite.has(id)) { seenCite.add(id); citedIds.push(id); } });
+  const base = location.hash.split('~')[0];
+
+  // TOP: contents + open questions (both collapsed, unobtrusive)
+  let top = '';
+  if (toc.length) top += contentsDisclosure(toc, base);
+  if (fm.open_questions?.length) top += openQuestionsDisclosure(fm.open_questions, false);
+  $('#docTop').innerHTML = top;
+
+  // BOTTOM: open questions (expanded) + the references + this-page links
+  let bot = '';
+  if (fm.open_questions?.length) bot += openQuestionsDisclosure(fm.open_questions, true);
+  bot += referencesSection(citedIds.length ? citedIds : (fm.sources || []));
+  bot += `<div class="page-links"><a href="${esc(RESOLVE)}/${esc(path)}" target="_blank" rel="noopener">raw markdown</a><a href="${esc(DATASET_BLOB)}/${esc(path)}" target="_blank" rel="noopener">source on HF ↗</a></div>`;
+  $('#docBottom').innerHTML = bot;
+}
+
+// collapsible <details> blocks used in the article flow
+function openQuestionsDisclosure(list, open) {
+  return `<details class="disclosure oq-d"${open ? ' open' : ''}>
+    <summary><span class="disc-ic">?</span> Open questions <span class="disc-n">${list.length}</span></summary>
+    <ul class="oq-list">${list.map(q => `<li>${renderInline(q)}</li>`).join('')}</ul>
+  </details>`;
+}
+function contentsDisclosure(toc, base) {
+  return `<details class="disclosure toc-d">
+    <summary><span class="disc-ic">≡</span> Contents <span class="disc-n">${toc.length}</span></summary>
+    <nav class="toc">${toc.map(t => `<a href="${base}~${t.slug}" class="${t.level === 3 ? 'h3' : ''}">${esc(t.text)}</a>`).join('')}</nav>
+  </details>`;
+}
+// references (sources cited), listed at the end of the article
+function referencesSection(ids) {
+  if (!ids.length) return '';
+  return `<section class="refs-section"><h2 class="refs-h">Sources cited<span class="refs-n">${ids.length}</span></h2>
+    <ol class="refs-list">${ids.map(id => {
+      const s = state.srcById.get(id); const ext = externalUrl(id);
+      return `<li><a class="ref-id" href="#/source/${encodeURIComponent(id)}" data-src="${esc(id)}">${esc(id)}</a>` +
+        (s && s.title ? `<span class="ref-title">${esc(s.title)}</span>` : '') +
+        (ext ? ` <a class="ref-ext" href="${esc(ext)}" target="_blank" rel="noopener" title="open the original">↗</a>` : '') + `</li>`;
+    }).join('')}</ol></section>`;
 }
 
 /* ── SOURCE RECORD ─────────────────────────────────────── */
@@ -994,27 +978,8 @@ function renderTopicsNav(list, q) {
     matches.forEach(n => {
       const it = el('div', 'nav-item');
       it.dataset.path = n.page.path;
-      const base = `#/topic/${encodeURIComponent(n.page.path)}`;
-      // All body occurrences of the query in this article (empty for a title-only match).
-      const { infos, total } = q && (state.searchText.get(n.page.path) || '').includes(q)
-        ? bodyMatchInfos(n.page.path, q) : { infos: [], total: 0 };
-      const titleTarget = base + (infos[0] && infos[0].section ? `~${infos[0].section}` : '');
-
-      const title = el('span', 'nav-item-title', highlightMatch(n.page.title || n.slug, q));
-      if (total > 1) title.append(el('span', 'nav-hit-count', String(total)));
-      it.append(title);
-      it.addEventListener('click', () => go(titleTarget));   // clicking the row → first hit / top
-
-      if (infos.length) {
-        const snips = el('div', 'nav-snippets');
-        infos.forEach(h => {
-          const s = el('div', 'nav-snippet', h.snippet);
-          s.addEventListener('click', (e) => { e.stopPropagation(); go(base + (h.section ? `~${h.section}` : '')); });
-          snips.append(s);
-        });
-        if (total > infos.length) snips.append(el('div', 'nav-snippet more', `+${total - infos.length} more match${total - infos.length === 1 ? '' : 'es'}`));
-        it.append(snips);
-      }
+      it.innerHTML = `${esc(n.page.title || n.slug)}`;
+      it.addEventListener('click', () => go(`#/topic/${encodeURIComponent(n.page.path)}`));
       body.append(it);
     });
     wrap.append(body);
@@ -1105,60 +1070,7 @@ function sortSources(items, mode) {
   else arr.sort((a, b) => (state.citeCount.get(b.id) || 0) - (state.citeCount.get(a.id) || 0) || (a.title || a.id).localeCompare(b.title || b.id));
   return arr;
 }
-// A page matches on its title, its path, or anywhere in its (background-indexed)
-// body. `q` is already lowercased by callers.
-const matchPage = (p, q) =>
-  (p.title || '').toLowerCase().includes(q) ||
-  p.path.toLowerCase().includes(q) ||
-  (state.searchText.get(p.path) || '').includes(q);
-// Every body occurrence of q in a page: a highlighted excerpt + its nearest heading,
-// so the sidebar can list all in-document hits and each can jump to its own section.
-// Returns { infos: [...], total } — total is the true count even when infos is capped.
-function bodyMatchInfos(path, q, cap = 20) {
-  const raw = state.pageContent.get(path), lc = state.searchText.get(path);
-  if (raw == null || lc == null) return { infos: [], total: 0 };
-  const text = parseFrontmatter(raw).body;   // same body the index was built from → indices align with lc and hits map to visible prose
-  const infos = []; let total = 0, i = lc.indexOf(q);
-  while (i >= 0) {
-    total++;
-    if (infos.length < cap) {
-      const start = Math.max(0, i - 30);
-      let clip = text.slice(start, i + q.length + 40)
-        .replace(/\[source:[^\]]*\]/g, ' ')
-        .replace(/[#>*_`~|]+/g, ' ')
-        .replace(/\s+/g, ' ').trim();
-      clip = (start > 0 ? '…' : '') + clip + '…';
-      infos.push({ snippet: highlightMatch(clip, q), section: headingSlugBefore(text, i) });
-    }
-    i = lc.indexOf(q, i + q.length);
-  }
-  return { infos, total };
-}
-// Slug of the last ##/###/#### heading before `pos`, replicating enhanceProse's
-// slugify + de-dup (and skipping fenced code) so the id matches the rendered anchor.
-function headingSlugBefore(md, pos) {
-  const seen = {};
-  let found = '', inFence = false, offset = 0;
-  for (const line of md.split('\n')) {
-    if (/^\s*(```|~~~)/.test(line)) inFence = !inFence;
-    else if (!inFence) {
-      const h = /^(#{2,4})\s+(.+?)\s*#*$/.exec(line);
-      if (h) {
-        let slug = h[2].trim().toLowerCase().replace(/[^\w\s-]/g, '').trim().replace(/\s+/g, '-').slice(0, 60) || 'sec';
-        if (seen[slug] != null) slug = `${slug}-${++seen[slug]}`; else seen[slug] = 0;
-        if (offset <= pos) found = slug;   // last heading at/before the match wins
-      }
-    }
-    offset += line.length + 1;   // +1 for the consumed '\n'
-  }
-  return found;
-}
-// Throttled nav re-render, used while background indexing fills in during a search.
-let _navRefreshT = null;
-function scheduleNavRefresh() {
-  if (_navRefreshT) return;
-  _navRefreshT = setTimeout(() => { _navRefreshT = null; if (($('#navSearch').value || '').trim()) renderNav(); }, 200);
-}
+const matchPage = (p, q) => (p.title || '').toLowerCase().includes(q) || p.path.toLowerCase().includes(q);
 const matchSource = (s, q) => (s.title || '').toLowerCase().includes(q) || s.id.toLowerCase().includes(q);
 function toggleCat(cat) {
   if (state.collapsed.has(cat)) state.collapsed.delete(cat); else state.collapsed.add(cat);
@@ -1180,6 +1092,30 @@ function highlightActive() {
    Filters an in-memory index, so it stays instant at thousands of items.
    ============================================================ */
 // `text` and `q` must already be lowercased (callers pre-lower for speed).
+function fuzzyScore(q, text) {
+  const idx = text.indexOf(q);
+  if (idx === 0) return 1000;            // prefix match — best
+  if (idx > 0) return 700 - Math.min(idx, 300);
+  // subsequence fallback — start at the first occurrence of q[0]; bail cheaply if absent.
+  let start = text.indexOf(q[0]);
+  if (start < 0) return -1;
+  let qi = 1, gaps = 0, last = start;
+  for (let ti = start + 1; ti < text.length && qi < q.length; ti++) {
+    if (text[ti] === q[qi]) { gaps += ti - last - 1; last = ti; qi++; }
+  }
+  return qi === q.length ? 300 - Math.min(gaps, 200) - Math.min(start, 50) : -1;
+}
+function paletteResults(raw) {
+  const q = raw.toLowerCase().trim();
+  if (!q) return state.palItems.slice(0, 40);
+  const scored = [];
+  for (const it of state.palItems) {
+    const s = Math.max(fuzzyScore(q, it._l), fuzzyScore(q, it._s) - 60);
+    if (s > -1) scored.push({ it, s });
+  }
+  scored.sort((a, b) => b.s - a.s || a.it.label.localeCompare(b.it.label));
+  return scored.slice(0, 40).map(x => x.it);
+}
 function highlightMatch(text, raw) {
   const q = raw.trim();
   if (!q) return esc(text);
@@ -1187,6 +1123,37 @@ function highlightMatch(text, raw) {
   if (i < 0) return esc(text);
   return esc(text.slice(0, i)) + '<b>' + esc(text.slice(i, i + q.length)) + '</b>' + esc(text.slice(i + q.length));
 }
+function renderPalette() {
+  const q = $('#palInput').value;
+  state.palFiltered = paletteResults(q);
+  if (state.palSel >= state.palFiltered.length) state.palSel = 0;
+  const box = $('#palResults');
+  if (!state.palFiltered.length) { box.innerHTML = `<div class="pal-empty">No matches for “${esc(q)}”.</div>`; return; }
+  box.innerHTML = state.palFiltered.map((it, i) => `
+    <div class="pal-item${i === state.palSel ? ' sel' : ''}" data-i="${i}">
+      <span class="pal-kind ${it.kind}">${it.kind}</span>
+      <span class="pal-text"><span class="pal-label">${highlightMatch(it.label, q)}</span><span class="pal-sub">${esc(it.sub)}</span></span>
+    </div>`).join('');
+  $$('#palResults .pal-item').forEach(n => {
+    n.addEventListener('mousemove', () => { if (state.palSel !== +n.dataset.i) { state.palSel = +n.dataset.i; markPalSel(); } });
+    n.addEventListener('click', () => choosePal(+n.dataset.i));
+  });
+}
+function markPalSel() { $$('#palResults .pal-item').forEach((n, i) => n.classList.toggle('sel', i === state.palSel)); }
+function scrollPalSel() { $$('#palResults .pal-item')[state.palSel]?.scrollIntoView({ block: 'nearest' }); }
+function choosePal(i) { const it = state.palFiltered[i]; if (it) { closePalette(); go(it.hash); } }
+function openPalette() {
+  const sc = $('#palScrim'); sc.hidden = false;
+  const inp = $('#palInput'); inp.value = ''; state.palSel = 0;
+  renderPalette(); inp.focus();
+}
+function closePalette() { $('#palScrim').hidden = true; }
+function palKeydown(e) {
+  if (e.key === 'ArrowDown') { e.preventDefault(); state.palSel = Math.min(state.palSel + 1, state.palFiltered.length - 1); markPalSel(); scrollPalSel(); }
+  else if (e.key === 'ArrowUp') { e.preventDefault(); state.palSel = Math.max(state.palSel - 1, 0); markPalSel(); scrollPalSel(); }
+  else if (e.key === 'Enter') { e.preventDefault(); choosePal(state.palSel); }
+  else if (e.key === 'Escape') { e.preventDefault(); closePalette(); }
+}
 
 /* ── mobile nav ───────────���────────────────────────────── */
 function closeNav() { document.body.classList.remove('nav-open'); }
@@ -1235,6 +1202,7 @@ async function loadCore() {
   }
   try { state.taxonomy = taxT && window.jsyaml ? jsyaml.load(taxT) : null; } catch (e) { state.taxonomy = null; }
   buildTaxonomy();
+  buildPaletteIndex();
 }
 const SOURCES_CACHE_KEY = 'viz-sources-v1';
 function setSources(items) {
@@ -1245,7 +1213,7 @@ function setSources(items) {
   if (items.some(s => s.title)) state.sourceTitlesLoaded = true;   // tree stage has none yet
 }
 function refreshSourceViews() {
-  updateCounts();
+  buildPaletteIndex(); updateCounts();
   softRefresh();          // re-renders the current view (incl. the sources browser), upgrading titles/resolution
 }
 // Reverse the filename sanitization (`:`/`/` → `-`): `arxiv-1707.06347.md` → `arxiv:1707.06347`.
@@ -1326,6 +1294,13 @@ function buildTaxonomy() {
   state.tax = cats;
 }
 
+function buildPaletteIndex() {
+  const mk = (kind, label, sub, hash) => ({ kind, label, sub, hash, _l: label.toLowerCase(), _s: sub.toLowerCase() });
+  state.palItems = [
+    ...state.pages.map(p => mk('topic', p.title || p.path, catLabel(p._cat || p.parent || ''), `#/topic/${encodeURIComponent(p.path)}`)),
+    ...state.sources.map(s => mk('source', s.title || s.id, s.id, `#/source/${encodeURIComponent(s.id)}`)),
+  ];
+}
 const catLabel = (c) => prettyTitle((c || '').replace(/-/g, ' '));
 // Sentence-cased category for headings, e.g. "reward-modeling" → "Reward modeling".
 const catDisplay = (c) => { const s = catLabel(c); return s.charAt(0).toUpperCase() + s.slice(1); };
@@ -1373,8 +1348,6 @@ async function ensureCitemap() {
         ids.forEach(id => { if (!state.citedBy.has(id)) state.citedBy.set(id, new Set()); state.citedBy.get(id).add(path); });
         state.refCount.set(path, refs);
         state.wordCount.set(path, countWords(content));
-        state.searchText.set(path, parseFrontmatter(content).body.toLowerCase());   // body only (frontmatter/open-questions excluded) so every hit maps to visible prose
-        if (($('#navSearch').value || '').trim()) scheduleNavRefresh();  // live-fill an in-progress search
       } catch (e) { /* skip unreadable article */ }
     }
   };
@@ -1427,30 +1400,18 @@ async function boot() {
   $('#navScrim').addEventListener('click', closeNav);
   $('#brandHome').addEventListener('click', () => go('#/'));
   let st;
-  const searchBadge = $('#paletteOpen');
-  const focusNavSearch = () => { const s = $('#navSearch'); s.focus(); s.select(); };
-  const clearNavSearch = () => { const s = $('#navSearch'); s.value = ''; syncSearchBadge(); renderNav(); refreshDocHighlights(''); s.focus(); };
-  // The badge is a ⌘K focus hint while empty, and a ✕ clear button once you've typed.
-  const syncSearchBadge = () => {
-    const has = !!$('#navSearch').value;
-    searchBadge.textContent = has ? '✕' : '⌘K';
-    searchBadge.classList.toggle('is-clear', has);
-    searchBadge.title = has ? 'Clear search' : 'Focus search (⌘K)';
-  };
-  $('#navSearch').addEventListener('input', () => {
-    ensureCitemap();   // kick off body indexing on first keystroke so content matches fill in fast
-    syncSearchBadge();
-    clearTimeout(st); st = setTimeout(() => { renderNav(); refreshDocHighlights($('#navSearch').value); }, 120);
-  });
+  $('#navSearch').addEventListener('input', () => { clearTimeout(st); st = setTimeout(renderNav, 120); });
   window.addEventListener('hashchange', route);
 
-  // ⌘K (and "/") focus the top-left search — one box that filters titles + bodies.
-  searchBadge.addEventListener('click', () => { $('#navSearch').value ? clearNavSearch() : focusNavSearch(); });
+  // command palette
+  $('#paletteOpen').addEventListener('click', openPalette);
+  $('#palInput').addEventListener('input', renderPalette);
+  $('#palInput').addEventListener('keydown', palKeydown);
+  $('#palScrim').addEventListener('click', (e) => { if (e.target === $('#palScrim')) closePalette(); });
   window.addEventListener('keydown', (e) => {
-    if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') { e.preventDefault(); focusNavSearch(); return; }
-    if (e.key === 'Escape' && document.activeElement === $('#navSearch') && $('#navSearch').value) { clearNavSearch(); return; }
+    if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') { e.preventDefault(); $('#palScrim').hidden ? openPalette() : closePalette(); return; }
     const typing = /^(input|textarea)$/i.test(document.activeElement?.tagName || '');
-    if (e.key === '/' && !typing) { e.preventDefault(); focusNavSearch(); }
+    if (e.key === '/' && !typing && $('#palScrim').hidden) { e.preventDefault(); openPalette(); }
   });
   initHovercards();
 

styles.css

@@ -24,8 +24,6 @@
   --accent-deep: #0a275f;
   --accent-soft: #dde6f5;
   --accent-hover-row: #c8d6ee;
-  --hl-bg: #0f3787;         /* search-hit rectangle */
-  --hl-ink: #ffffff;
   --good: #1c7c3f;
   --warn: #9a6b00;
   --danger: #a12d2d;
@@ -55,8 +53,6 @@
   --accent-deep: #b6cdf7;
   --accent-soft: #20304d;
   --accent-hover-row: #28395a;
-  --hl-bg: #4f7fe0;
-  --hl-ink: #ffffff;
   --good: #6fcf8f;
   --warn: #e0b15a;
   --danger: #e08585;
@@ -163,7 +159,7 @@ a:hover { color: var(--accent-deep); }
   content: "⌕"; position: absolute; left: 9px; top: 50%; transform: translateY(-50%);
   color: var(--muted-3); font-size: 15px;
 }
-/* the ⌘K badge on the search box: click (or ⌘K) → focus the search input */
+/* the one global-search affordance: click (or ⌘K) → command palette */
 .search-k {
   position: absolute; right: 7px; top: 50%; transform: translateY(-50%);
   font-family: var(--mono); font-size: 10px; padding: 2px 6px; border-radius: 4px;
@@ -171,9 +167,6 @@ a:hover { color: var(--accent-deep); }
   cursor: pointer; transition: all .12s;
 }
 .search-k:hover { border-color: var(--accent); color: var(--accent-deep); }
-/* once a query is entered, the badge becomes a ✕ clear button */
-.search-k.is-clear { font-family: var(--sans); font-size: 12px; line-height: 1; padding: 3px 6.5px; }
-.search-k.is-clear:hover { background: var(--accent-soft); }
 
 .nav-group { margin-bottom: 14px; }
 .nav-group-title {
@@ -198,25 +191,6 @@ a:hover { color: var(--accent-deep); }
   display: block; font-family: var(--mono); font-size: 9.5px;
   color: var(--muted-4); margin-top: 1px; letter-spacing: 0.2px;
 }
-/* content-search: a matched-body excerpt under the topic name, query bolded */
-.nav-item .nav-item-title { display: block; }
-.nav-item .nav-item-title b { color: var(--accent-deep); font-weight: 600; }
-.nav-item .nav-snippets { display: block; margin-top: 2px; }
-.nav-item .nav-snippet {
-  display: block; margin-top: 2px; padding: 2px 6px; font-size: 11px; line-height: 1.4;
-  color: var(--muted-3); font-weight: 400; cursor: pointer;
-  border-left: 2px solid var(--border); border-radius: 0 4px 4px 0;
-  transition: background .12s, border-color .12s, color .12s;
-}
-.nav-item .nav-snippet:hover { background: var(--accent-soft); border-left-color: var(--accent); color: var(--ink); }
-.nav-item .nav-snippet b { color: var(--accent-deep); font-weight: 600; }
-.nav-item .nav-snippet.more { font-style: italic; cursor: default; border-left-color: transparent; color: var(--muted-4); }
-.nav-item .nav-snippet.more:hover { background: none; }
-.nav-hit-count {
-  display: inline-block; margin-left: 5px; padding: 0 5px; font-family: var(--mono);
-  font-size: 9px; line-height: 15px; vertical-align: 1px; border-radius: 8px;
-  background: var(--accent-soft); color: var(--accent-deep); font-weight: 600;
-}
 .nav-empty { color: var(--muted-4); font-size: 11.5px; padding: 8px; font-style: italic; }
 .mini-spin { display: inline-block; width: 10px; height: 10px; vertical-align: -1px; margin-right: 4px;
   border: 1.5px solid var(--border); border-top-color: var(--accent); border-radius: 50%; animation: spin .7s linear infinite; }
@@ -234,6 +208,49 @@ a:hover { color: var(--accent-deep); }
 .crumbs .sep { color: var(--muted-5); }
 
 /* doc header */
+/* single reading column for topic articles (no right rail) */
+.doc { max-width: 820px; margin: 0 auto; }
+.doc .prose { max-width: none; }
+
+/* collapsible disclosures used in the article flow (Contents, Open questions) */
+.disclosure { border: 1px solid var(--border); border-radius: 9px; background: var(--bg-card); margin: 14px 0; overflow: hidden; }
+.disclosure > summary {
+  list-style: none; cursor: pointer; padding: 10px 14px; display: flex; align-items: center; gap: 8px;
+  font-family: var(--mono); font-size: 12px; font-weight: 600; letter-spacing: 0.4px; text-transform: uppercase; color: var(--ink-3);
+}
+.disclosure > summary::-webkit-details-marker { display: none; }
+.disclosure > summary:hover { color: var(--ink); }
+.disclosure > summary::after { content: "▸"; margin-left: auto; color: var(--muted-4); transition: transform .15s; }
+.disclosure[open] > summary::after { transform: rotate(90deg); }
+.disclosure .disc-ic { color: var(--accent); font-weight: 700; }
+.disclosure .disc-n { color: var(--muted-4); font-weight: 500; }
+.disclosure.oq-d { border-left: 3px solid var(--accent); }
+.disclosure .oq-list, .disclosure .toc { padding: 2px 16px 14px; }
+.disclosure .toc { display: block; }
+.disclosure .toc a { display: block; font-size: 12.5px; color: var(--muted); padding: 3px 0 3px 10px; border-left: 2px solid var(--border-soft); }
+.disclosure .toc a.h3 { padding-left: 22px; font-size: 11.5px; }
+.disclosure .toc a:hover { color: var(--accent); border-left-color: var(--accent); }
+
+/* references (sources cited), at the end of the article */
+.refs-section { margin: 40px 0 8px; padding-top: 20px; border-top: 1px solid var(--border); }
+.refs-h { font-family: var(--mono); font-size: 15px; font-weight: 600; color: var(--ink); margin-bottom: 12px; display: flex; align-items: baseline; gap: 8px; }
+.refs-h .refs-n { font-size: 11px; color: var(--muted-4); font-weight: 500; }
+.refs-list { list-style: decimal; margin: 0 0 0 26px; padding: 0; }
+.refs-list li { margin: 5px 0; font-size: 13px; line-height: 1.5; }
+.refs-list li::marker { color: var(--muted-4); font-family: var(--mono); font-size: 11px; }
+.ref-id { font-family: var(--mono); font-size: 11.5px; color: var(--accent); border-bottom: none; }
+.ref-id:hover { border-bottom: 1px solid var(--accent); }
+.ref-title { color: var(--ink-3); margin-left: 8px; }
+.ref-ext { color: var(--muted-4); border-bottom: none; }
+.page-links { margin: 22px 0 0; display: flex; gap: 16px; font-family: var(--mono); font-size: 11px; }
+.page-links a { color: var(--muted-3); }
+.page-links a:hover { color: var(--accent); }
+
+/* figures — images, inline SVG diagrams, generated plots */
+.prose .fig { margin: 22px 0; text-align: center; }
+.prose .fig img, .prose .fig svg { max-width: 100%; height: auto; border-radius: 8px; }
+.prose .fig figcaption { font-size: 12px; color: var(--muted-2); margin-top: 8px; line-height: 1.45; text-align: center; }
+
 .doc-head { margin-bottom: 18px; padding-bottom: 16px; border-bottom: 1px solid var(--border); }
 .doc-kicker {
   font-family: var(--mono); font-size: 10.5px; letter-spacing: 1.5px;
@@ -338,23 +355,6 @@ a:hover { color: var(--accent-deep); }
   font-size: 12.8px; line-height: 1.55;
 }
 .prose pre code { background: none; border: none; padding: 0; font-size: inherit; color: var(--ink-2); }
-/* cross-reference: a `category/node` code span linked to its topic page */
-.prose a.xref { border-bottom: none; text-decoration: none; }
-.prose a.xref code {
-  background: var(--accent-soft); border-color: transparent; color: var(--accent-deep);
-  cursor: pointer; transition: background .12s, color .12s;
-}
-.prose a.xref:hover code { background: var(--accent); color: #fff; }
-[data-theme="dark"] .prose a.xref:hover code { color: #0b1220; }
-/* active-search term highlighting inside the article (cleared with the search) —
-   bold, slightly larger blue text (no pill, so it doesn't read like a link chip) */
-mark.search-hl {
-  background: var(--hl-bg); color: var(--hl-ink);
-  font-weight: 600; border-radius: 3px;
-  padding: 0.5px 3.5px; margin: 0 0.5px;
-  box-shadow: 0 0 0 1px var(--hl-bg);
-  -webkit-box-decoration-break: clone; box-decoration-break: clone;
-}
 
 /* blockquote */
 .prose blockquote {
@@ -595,6 +595,52 @@ mark.search-hl {
 }
 @media (min-width: 901px) { .nav-scrim { display: none !important; } }
 
+/* ── command palette ───────────────────────────────────── */
+.palette-foot kbd, .pal-esc {
+  font-family: var(--mono); font-size: 10px; padding: 1.5px 5px; border-radius: 4px;
+  border: 1px solid var(--border); background: var(--bg-soft); color: var(--muted-2); line-height: 1.4;
+}
+
+.palette-scrim {
+  position: fixed; inset: 0; z-index: 200; background: rgba(15,18,22,0.42);
+  backdrop-filter: blur(2px); display: flex; align-items: flex-start; justify-content: center;
+  padding: 12vh 16px 16px;
+}
+.palette-scrim[hidden] { display: none; }
+.palette {
+  width: 100%; max-width: 580px; background: var(--bg-card); border: 1px solid var(--border);
+  border-radius: 12px; box-shadow: 0 12px 48px rgba(0,0,0,0.28); overflow: hidden;
+  display: flex; flex-direction: column; max-height: 70vh;
+}
+.palette-search { display: flex; align-items: center; gap: 10px; padding: 12px 15px; border-bottom: 1px solid var(--border); }
+.pal-icon { color: var(--muted-3); font-size: 17px; }
+.palette-input {
+  flex: 1; border: none; background: none; outline: none; color: var(--ink);
+  font-family: var(--sans); font-size: 15px; font-weight: 300;
+}
+.palette-results { overflow-y: auto; padding: 6px; }
+.pal-item {
+  display: flex; align-items: center; gap: 10px; padding: 8px 10px; border-radius: 7px; cursor: pointer;
+}
+.pal-item.sel { background: var(--accent-soft); }
+.pal-kind {
+  flex: 0 0 auto; font-family: var(--mono); font-size: 9px; font-weight: 600; text-transform: uppercase;
+  letter-spacing: 0.5px; padding: 2px 6px; border-radius: 4px; width: 50px; text-align: center;
+}
+.pal-kind.topic { background: var(--accent-soft); color: var(--accent-deep); }
+.pal-kind.source { background: var(--bg-soft); color: var(--muted-2); border: 1px solid var(--border-soft); }
+.pal-text { flex: 1; min-width: 0; }
+.pal-label { font-size: 13.5px; color: var(--ink); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.pal-label b { color: var(--accent-deep); font-weight: 600; }
+.pal-sub { font-family: var(--mono); font-size: 10px; color: var(--muted-4); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.pal-empty { padding: 24px; text-align: center; color: var(--muted-3); font-size: 13px; }
+.palette-foot {
+  display: flex; gap: 14px; align-items: center; padding: 8px 14px; border-top: 1px solid var(--border-soft);
+  font-size: 10.5px; color: var(--muted-3); font-family: var(--mono); flex-wrap: wrap;
+}
+.pal-dot { display: inline-block; width: 7px; height: 7px; border-radius: 50%; vertical-align: middle; margin: 0 2px 0 6px; }
+.pal-dot.pal-t { background: var(--accent); }
+.pal-dot.pal-s { background: var(--muted-4); }
 
 /* ── Collapsible taxonomy tree (topics sidebar) ────────── */
 .nav-cat { margin-bottom: 10px; }
@@ -768,7 +814,7 @@ body.book-mode .main { padding: 0; }
 
 /* ── Print (browser "Save as PDF") ─────────────────────── */
 @media print {
-  .topbar, .sidebar, .aside, .nav-scrim, .book-toolbar, #hovercard, #toast, .foot, .menu-toggle { display: none !important; }
+  .topbar, .sidebar, .aside, .nav-scrim, .book-toolbar, .palette-scrim, #hovercard, #toast, .foot, .menu-toggle { display: none !important; }
   html, body { background: #fff; color: #000; }
   .layout, .main, body.book-mode .main { display: block; padding: 0; margin: 0; }
   .book { max-width: none; margin: 0; padding: 0; color: #111; font-size: 10.5pt; }
@@ -787,4 +833,11 @@ body.book-mode .main { padding: 0; }
   .cite .cite-mark { display: none; }
   a.secref { color: #111; border: none; }
   .prose abbr.ac { border: none; }
+  /* single-article print: show collapsed disclosures + drop their chrome */
+  .disclosure { border: none; }
+  .disclosure > summary { padding-left: 0; }
+  .disclosure > summary::after { display: none; }
+  .disclosure > *:not(summary) { display: block !important; }
+  .page-links { display: none; }
+  .prose .fig { break-inside: avoid; }
 }