Fix critical GP numerical stability, import/export, and quiz UX bugs

jeremymanning · claude · jeremymanning · commit 0acfac670b5d · 2026-02-19T21:03:56.000-05:00
- Fix NaN/red-collapse: increase Cholesky jitter from 1e-10 to 1e-6,
  add NaN fallback in choleskySolve (returns zero vector instead of NaN),
  add isFinite guards in estimator predict, $coverage, updateConfidence,
  and computeConceptKnowledge
- Fix JSON import: keep FileReader input reference to prevent GC,
  add onerror handler, include x/y coordinates in exports, look up
  missing coords from questionIndex during import
- Replace auto-advance with explicit "Next" button after answering,
  giving users time to read correct answer feedback
- Add "Learn more" buttons (Wikipedia + Khan Academy) after each answer
- Add keyboard shortcut (Enter/N/Space) to advance to next question
- Fix knowledge bars in expertise/learning modals (NaN propagation)
- Fix race condition causing wrong answer options for different question
  (eliminated by removing setTimeout chain in answer flow)

Co-Authored-By: Claude (claude-opus-4-6) &lt;noreply@anthropic.com&gt;
diff --git a/src/app.js b/src/app.js
@@ -115,6 +115,7 @@ async function boot() {
   const quizPanel = document.getElementById('quiz-panel');
   quiz.init(quizPanel);
   quiz.onAnswer(handleAnswer);
+  quiz.onNext(() => selectAndShowNextQuestion());
 
   renderer.onReanswer((questionId) => {
     const q = questionIndex.get(questionId);
@@ -450,10 +451,7 @@ function handleAnswer(selectedKey, question) {
   
   const coverage = Math.round($coverage.get() * 100);
   announce(`${feedback} ${coverage}% of domain mapped. ${50 - domainQuestionCount} questions remaining.`);
-
-  setTimeout(() => {
-    selectAndShowNextQuestion();
-  }, 900);
+  // No auto-advance — user clicks "Next" button in quiz panel
 }
 
 function handleReset() {
@@ -523,9 +521,26 @@ function handleImport(data) {
     return;
   }
 
+  // Enrich imported responses with x/y coordinates from questionIndex
+  // (older exports may lack these, but we need them for the GP estimator)
+  let coordsRecovered = 0;
+  const enrichedValid = valid.map(r => {
+    if (r.x != null && r.y != null) return r;
+    const q = questionIndex.get(r.question_id);
+    if (q && q.x != null && q.y != null) {
+      coordsRecovered++;
+      return { ...r, x: q.x, y: q.y };
+    }
+    return r;
+  });
+
+  if (coordsRecovered > 0) {
+    console.log(`[import] Recovered x/y coordinates for ${coordsRecovered} responses from question index`);
+  }
+
   const existing = $responses.get();
   const existingIds = new Set(existing.map(r => r.question_id));
-  const newResponses = valid.filter(r => !existingIds.has(r.question_id));
+  const newResponses = enrichedValid.filter(r => !existingIds.has(r.question_id));
   const merged = [...existing, ...newResponses];
 
   $responses.set(merged);
diff --git a/src/learning/estimator.js b/src/learning/estimator.js
@@ -145,7 +145,11 @@ export class Estimator {
         state = 'estimated';
       }
 
-      results[i] = { gx: cell.gx, gy: cell.gy, value, uncertainty, evidenceCount, state };
+      // NaN safety: if numerical instability produced bad values, use prior
+      const safeValue = isFinite(value) ? value : PRIOR_MEAN;
+      const safeUncertainty = isFinite(uncertainty) ? uncertainty : 1.0;
+
+      results[i] = { gx: cell.gx, gy: cell.gy, value: safeValue, uncertainty: safeUncertainty, evidenceCount, state };
     }
 
     return results;
@@ -201,7 +205,11 @@ export class Estimator {
       state = 'estimated';
     }
 
-    return { gx, gy, value, uncertainty, evidenceCount, state };
+    // NaN safety: if numerical instability produced bad values, use prior
+    const safeValue = isFinite(value) ? value : PRIOR_MEAN;
+    const safeUncertainty = isFinite(uncertainty) ? uncertainty : 1.0;
+
+    return { gx, gy, value: safeValue, uncertainty: safeUncertainty, evidenceCount, state };
   }
 
   /**
@@ -291,6 +299,11 @@ export class Estimator {
     }
 
     this._alpha = choleskySolve(this._K_noisy, this._obsValues);
+
+    // Safety: if Cholesky returned a zero vector (NaN fallback), log a warning
+    if (this._alpha.every(v => v === 0) && this._obsValues.some(v => v !== 0)) {
+      console.warn('[estimator] Cholesky returned fallback zero vector — predictions will use prior mean');
+    }
   }
 
   /**
diff --git a/src/state/persistence.js b/src/state/persistence.js
@@ -29,6 +29,8 @@ export function exportResponses() {
       selected: r.selected,
       is_correct: r.is_correct,
       timestamp: r.timestamp,
+      x: r.x,
+      y: r.y,
     })),
   };
   return new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
diff --git a/src/state/store.js b/src/state/store.js
@@ -47,10 +47,12 @@ export const $coverage = computed($estimates, (estimates) => {
   let totalCoverage = 0;
   for (const e of estimates) {
     if (e.state === 'unknown') continue;
-    // Each cell contributes (1 - uncertainty) — well-evidenced cells contribute more
-    totalCoverage += (1 - e.uncertainty);
+    const contrib = 1 - e.uncertainty;
+    // Guard against NaN from numerical instability in GP
+    if (isFinite(contrib)) totalCoverage += contrib;
   }
-  return totalCoverage / estimates.length;
+  const result = totalCoverage / estimates.length;
+  return isFinite(result) ? result : 0;
 });
 
 /** Whether insights are available (>= 10 responses) */
diff --git a/src/ui/controls.js b/src/ui/controls.js
@@ -206,11 +206,14 @@ export function init(headerElement) {
   importButton.title = 'Import saved progress';
   importButton.innerHTML = '<i class="fa-solid fa-upload"></i>';
   importButton.hidden = true;
+  // Keep a module-level reference to avoid GC before FileReader fires
+  let _importInput = null;
+
   importButton.addEventListener('click', () => {
-    const input = document.createElement('input');
-    input.type = 'file';
-    input.accept = '.json,application/json';
-    input.addEventListener('change', (e) => {
+    _importInput = document.createElement('input');
+    _importInput.type = 'file';
+    _importInput.accept = '.json,application/json';
+    _importInput.addEventListener('change', (e) => {
       const file = e.target.files[0];
       if (!file) return;
       const reader = new FileReader();
@@ -222,10 +225,16 @@ export function init(headerElement) {
           console.error('[controls] Failed to parse import file:', err);
           alert('Invalid file format. Please select a Knowledge Mapper export JSON file.');
         }
+        _importInput = null; // Release reference after successful read
+      };
+      reader.onerror = () => {
+        console.error('[controls] FileReader error:', reader.error);
+        alert('Could not read file. Please try again.');
+        _importInput = null;
       };
       reader.readAsText(file);
     });
-    input.click();
+    _importInput.click();
   });
   container.appendChild(importButton);
 
diff --git a/src/ui/insights.js b/src/ui/insights.js
@@ -222,7 +222,8 @@ export function computeConceptKnowledge(estimates, region, gridSize, opts = {})
   function knowledgeAt(x, y) {
     const gx = Math.min(gridSize - 1, Math.max(0, Math.floor((x - region.x_min) / cellW)));
     const gy = Math.min(gridSize - 1, Math.max(0, Math.floor((y - region.y_min) / cellH)));
-    return estimateMap.get(`${gx},${gy}`) ?? 0.5;
+    const val = estimateMap.get(`${gx},${gy}`) ?? 0.5;
+    return isFinite(val) ? val : 0.5; // Guard against NaN from GP instability
   }
 
   const results = [];
@@ -231,7 +232,8 @@ export function computeConceptKnowledge(estimates, region, gridSize, opts = {})
     for (const c of pts) {
       sum += knowledgeAt(c.x, c.y);
     }
-    results.push({ concept, knowledge: sum / pts.length, count: pts.length });
+    const knowledge = pts.length > 0 ? sum / pts.length : 0.5;
+    results.push({ concept, knowledge: isFinite(knowledge) ? knowledge : 0.5, count: pts.length });
   }
 
   return results;
diff --git a/src/ui/progress.js b/src/ui/progress.js
@@ -113,8 +113,10 @@ export function initConfidence(container) {
 
 export function updateConfidence(coverage) {
   if (!confidenceFill || !confidenceText) return;
-  
-  const pct = Math.min(100, Math.max(0, coverage * 100));
+
+  // Guard against NaN from GP numerical instability
+  const safeCoverage = isFinite(coverage) ? coverage : 0;
+  const pct = Math.min(100, Math.max(0, safeCoverage * 100));
   confidenceFill.style.width = `${pct}%`;
   confidenceText.textContent = `Domain mapped: ${Math.round(pct)}%`;
 }
diff --git a/src/ui/quiz.js b/src/ui/quiz.js
@@ -3,6 +3,7 @@
 import { announce } from '../utils/accessibility.js';
 
 let answerCallback = null;
+let nextCallback = null;
 let currentQuestion = null;
 let uiElements = {};
 
@@ -110,6 +111,50 @@ export function init(container) {
       .quiz-meta a:hover {
         text-shadow: 0 0 6px var(--color-glow-secondary);
       }
+      .quiz-actions {
+        display: flex;
+        gap: 0.5rem;
+        margin-top: 0.75rem;
+        flex-wrap: wrap;
+      }
+      .quiz-next-btn {
+        padding: 0.5rem 1.25rem;
+        border-radius: 8px;
+        border: 1px solid var(--color-primary);
+        background: var(--color-primary);
+        color: #ffffff;
+        font-family: var(--font-heading);
+        font-size: 0.82rem;
+        font-weight: 600;
+        cursor: pointer;
+        transition: all 0.2s ease;
+        min-height: 36px;
+      }
+      .quiz-next-btn:hover {
+        box-shadow: 0 0 12px var(--color-glow-primary);
+        transform: translateY(-1px);
+      }
+      .quiz-learn-btn {
+        padding: 0.4rem 0.75rem;
+        border-radius: 6px;
+        border: 1px solid var(--color-border);
+        background: var(--color-surface-raised);
+        color: var(--color-text-muted);
+        font-family: var(--font-body);
+        font-size: 0.75rem;
+        cursor: pointer;
+        transition: all 0.2s ease;
+        text-decoration: none;
+        display: inline-flex;
+        align-items: center;
+        gap: 0.35rem;
+        min-height: 32px;
+      }
+      .quiz-learn-btn:hover {
+        border-color: var(--color-secondary);
+        color: var(--color-secondary);
+        box-shadow: 0 0 8px var(--color-glow-secondary);
+      }
       .katex { font-size: 1.05em; }
     `;
     document.head.appendChild(style);
@@ -128,6 +173,11 @@ export function init(container) {
         <button class="quiz-option" data-key="D" aria-label="Option D"></button>
       </div>
       <div class="quiz-feedback" aria-live="assertive"></div>
+      <div class="quiz-actions" hidden>
+        <button class="quiz-next-btn" aria-label="Next question">Next <i class="fa-solid fa-arrow-right" style="margin-left:0.3rem;font-size:0.75rem"></i></button>
+        <a class="quiz-learn-btn" target="_blank" rel="noopener" data-learn="wikipedia" hidden><i class="fa-brands fa-wikipedia-w"></i> Wikipedia</a>
+        <a class="quiz-learn-btn" target="_blank" rel="noopener" data-learn="khan" hidden><i class="fa-solid fa-graduation-cap"></i> Khan Academy</a>
+      </div>
       <div class="quiz-meta"></div>
     </div>
   `;
@@ -138,6 +188,10 @@ export function init(container) {
     instruction: container.querySelector('.quiz-instruction'),
     options: container.querySelectorAll('.quiz-option'),
     feedback: container.querySelector('.quiz-feedback'),
+    actions: container.querySelector('.quiz-actions'),
+    nextBtn: container.querySelector('.quiz-next-btn'),
+    wikiBtn: container.querySelector('[data-learn="wikipedia"]'),
+    khanBtn: container.querySelector('[data-learn="khan"]'),
     meta: container.querySelector('.quiz-meta')
   };
 
@@ -146,6 +200,12 @@ export function init(container) {
     btn.addEventListener('click', () => handleOptionClick(btn.dataset.key));
   });
 
+  if (uiElements.nextBtn) {
+    uiElements.nextBtn.addEventListener('click', () => {
+      if (nextCallback) nextCallback();
+    });
+  }
+
   document.addEventListener('keydown', handleKeyDown);
 
   const resizeHandle = container.querySelector('.resize-handle');
@@ -174,7 +234,15 @@ export function init(container) {
 
 function handleKeyDown(e) {
   if (!currentQuestion || !uiElements.options) return;
-  if (uiElements.options[0].disabled) return;
+
+  // If options are disabled (already answered), Enter/N/Space advances to next
+  if (uiElements.options[0].disabled) {
+    if (e.key === 'Enter' || e.key === 'n' || e.key === 'N' || e.key === ' ') {
+      e.preventDefault();
+      if (nextCallback) nextCallback();
+    }
+    return;
+  }
 
   const key = e.key.toUpperCase();
   if (['1', 'A'].includes(key)) handleOptionClick('A');
@@ -218,7 +286,12 @@ export function showQuestion(question) {
   }
   
   if (uiElements.meta) {
-    uiElements.meta.innerHTML = '';
+    uiElements.meta.textContent = '';
+  }
+
+  // Hide Next/Learn more buttons until answer is given
+  if (uiElements.actions) {
+    uiElements.actions.hidden = true;
   }
 }
 
@@ -256,20 +329,56 @@ function handleOptionClick(selectedKey) {
   if (uiElements.meta && currentQuestion.source_article) {
     const article = currentQuestion.source_article;
     const url = `https://en.wikipedia.org/wiki/${encodeURIComponent(article)}`;
-    uiElements.meta.innerHTML = `Source: <a href="${url}" target="_blank">${article}</a>`;
+    uiElements.meta.textContent = '';
+    const sourceLabel = document.createTextNode('Source: ');
+    const sourceLink = document.createElement('a');
+    sourceLink.href = url;
+    sourceLink.target = '_blank';
+    sourceLink.textContent = article;
+    uiElements.meta.appendChild(sourceLabel);
+    uiElements.meta.appendChild(sourceLink);
   }
 
+  // Show Next button and Learn more links instead of auto-advancing
+  if (uiElements.actions) {
+    uiElements.actions.hidden = false;
+
+    // Show Wikipedia link if we have a source article
+    if (uiElements.wikiBtn && currentQuestion.source_article) {
+      const wikiUrl = `https://en.wikipedia.org/wiki/${encodeURIComponent(currentQuestion.source_article)}`;
+      uiElements.wikiBtn.href = wikiUrl;
+      uiElements.wikiBtn.hidden = false;
+    } else if (uiElements.wikiBtn) {
+      uiElements.wikiBtn.hidden = true;
+    }
+
+    // Show Khan Academy search link based on question concepts or article
+    if (uiElements.khanBtn) {
+      const searchTerm = currentQuestion.source_article || '';
+      if (searchTerm) {
+        uiElements.khanBtn.href = `https://www.khanacademy.org/search?referer=%2F&page_search_query=${encodeURIComponent(searchTerm)}`;
+        uiElements.khanBtn.hidden = false;
+      } else {
+        uiElements.khanBtn.hidden = true;
+      }
+    }
+  }
+
+  // Fire the answer callback immediately (records the response and updates estimator)
+  // but do NOT auto-advance to next question — user clicks "Next" when ready
   if (answerCallback) {
-    setTimeout(() => {
-      answerCallback(selectedKey, currentQuestion);
-    }, 800);
+    answerCallback(selectedKey, currentQuestion);
   }
 }
 
 export function onAnswer(callback) {
   answerCallback = callback;
 }
 
+export function onNext(callback) {
+  nextCallback = callback;
+}
+
 /**
  * Replaces $...$ with KaTeX rendered HTML.
  * Heuristic: if content between $ signs contains only numbers/punctuation, treat as currency.
diff --git a/src/utils/math.js b/src/utils/math.js

Original file line number	Diff line number	Diff line change
`@@ -145,7 +145,11 @@ export class Estimator {`
`145`	`145`	`state = 'estimated';`
`146`	`146`	`}`
`147`	`147`
`148`		`- results[i] = { gx: cell.gx, gy: cell.gy, value, uncertainty, evidenceCount, state };`
	`148`	`+ // NaN safety: if numerical instability produced bad values, use prior`
	`149`	`+ const safeValue = isFinite(value) ? value : PRIOR_MEAN;`
	`150`	`+ const safeUncertainty = isFinite(uncertainty) ? uncertainty : 1.0;`
	`151`	`+`
	`152`	`+ results[i] = { gx: cell.gx, gy: cell.gy, value: safeValue, uncertainty: safeUncertainty, evidenceCount, state };`
`149`	`153`	`}`
`150`	`154`
`151`	`155`	`return results;`
`@@ -201,7 +205,11 @@ export class Estimator {`
`201`	`205`	`state = 'estimated';`
`202`	`206`	`}`
`203`	`207`
`204`		`- return { gx, gy, value, uncertainty, evidenceCount, state };`
	`208`	`+ // NaN safety: if numerical instability produced bad values, use prior`
	`209`	`+ const safeValue = isFinite(value) ? value : PRIOR_MEAN;`
	`210`	`+ const safeUncertainty = isFinite(uncertainty) ? uncertainty : 1.0;`
	`211`	`+`
	`212`	`+ return { gx, gy, value: safeValue, uncertainty: safeUncertainty, evidenceCount, state };`
`205`	`213`	`}`
`206`	`214`
`207`	`215`	`/**`
`@@ -291,6 +299,11 @@ export class Estimator {`
`291`	`299`	`}`
`292`	`300`
`293`	`301`	`this._alpha = choleskySolve(this._K_noisy, this._obsValues);`
	`302`	`+`
	`303`	`+ // Safety: if Cholesky returned a zero vector (NaN fallback), log a warning`
	`304`	`+ if (this._alpha.every(v => v === 0) && this._obsValues.some(v => v !== 0)) {`
	`305`	`+ console.warn('[estimator] Cholesky returned fallback zero vector — predictions will use prior mean');`
	`306`	`+ }`
`294`	`307`	`}`
`295`	`308`
`296`	`309`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -222,7 +222,8 @@ export function computeConceptKnowledge(estimates, region, gridSize, opts = {})`
`222`	`222`	`function knowledgeAt(x, y) {`
`223`	`223`	`const gx = Math.min(gridSize - 1, Math.max(0, Math.floor((x - region.x_min) / cellW)));`
`224`	`224`	`const gy = Math.min(gridSize - 1, Math.max(0, Math.floor((y - region.y_min) / cellH)));`
`225`		- return estimateMap.get(`${gx},${gy}`) ?? 0.5;
	`225`	+ const val = estimateMap.get(`${gx},${gy}`) ?? 0.5;
	`226`	`+ return isFinite(val) ? val : 0.5; // Guard against NaN from GP instability`
`226`	`227`	`}`
`227`	`228`
`228`	`229`	`const results = [];`
`@@ -231,7 +232,8 @@ export function computeConceptKnowledge(estimates, region, gridSize, opts = {})`
`231`	`232`	`for (const c of pts) {`
`232`	`233`	`sum += knowledgeAt(c.x, c.y);`
`233`	`234`	`}`
`234`		`- results.push({ concept, knowledge: sum / pts.length, count: pts.length });`
	`235`	`+ const knowledge = pts.length > 0 ? sum / pts.length : 0.5;`
	`236`	`+ results.push({ concept, knowledge: isFinite(knowledge) ? knowledge : 0.5, count: pts.length });`
`235`	`237`	`}`
`236`	`238`
`237`	`239`	`return results;`