@vue-skuilder/db 0.2.4 → 0.2.5

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.2.4",
+    "@vue-skuilder/common": "0.2.5",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -62,5 +62,5 @@
     "vite": "^8.0.0",
     "vitest": "^4.1.0"
   },
-  "stableVersion": "0.2.4"
+  "stableVersion": "0.2.5"
 }

package/src/core/navigators/generators/elo.ts

@@ -7,6 +7,13 @@ import type { QualifiedCardID } from '../..';
 import type { CardGenerator, GeneratorContext, GeneratorResult } from './types';
 import { logger } from '@db/util/logger';
 
+/**
+ * Std-dev (in ELO points) of the Gaussian that converts card↔user ELO distance
+ * into a relevance weight. 300 reproduces the legacy linear ramp's half-weight
+ * point (distance 250 → ~0.5) while removing its hard zero beyond distance 500.
+ */
+const ELO_RELEVANCE_SIGMA = 300;
+
 // ============================================================================
 // ELO NAVIGATOR
 // ============================================================================
@@ -96,17 +103,31 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
         // `[active=${activeCards.length} candidates=${newCards.length}]`
     // );
 
-    // Score new cards by ELO distance, then apply weighted sampling without
-    // replacement using the Efraimidis-Spirakis (A-Res) algorithm:
+    // Score new cards by ELO proximity, then apply bounded multiplicative
+    // jitter for session-to-session variety.
     //
-    //   key = U ^ (1 / rawScore)   where U ~ Uniform(0, 1)
+    //   relevance = exp(-(distance / SIGMA)^2)   // Gaussian: smooth, always > 0
+    //   score     = relevance * (0.5 + 0.5 * U)  // U ~ Uniform(0, 1)
     //
-    // Sorting by key descending produces a weighted random sample: high-score
-    // cards are still preferred, but cards with equal scores are shuffled
-    // uniformly rather than deterministically. This prevents the same failed
-    // cards from looping back every session when many cards share similar ELO.
+    // This replaces the legacy `rawScore = max(0, 1 - distance/500)` ramp +
+    // Efraimidis-Spirakis key `U^(1/rawScore)`, which introduced two
+    // discontinuities that defeated downstream replan boosts:
+    //   1. The ramp's clamp made every card ≥500 ELO from the user a HARD zero.
+    //      The pipeline DELETES zero-score cards (filter score>0) *before* boosts
+    //      are applied, so no boost could resurface an under-ELO'd target — e.g.
+    //      a freshly-introduced grapheme sitting ~475 below an inflated global
+    //      ELO. (See packages/db/docs/todo-intro-concept-emphasis-and-retrieval.md.)
+    //   2. The A-Res key `U^(1/rawScore)` ALSO manufactured effective zeros: as
+    //      rawScore→0 the exponent explodes and `U^huge` underflows to 0, with
+    //      wild variance just above it — so a downstream boost multiplied a
+    //      lottery ticket rather than a stable relevance.
     //
-    // Edge case: rawScore=0 → key=0, never selected (correct exclusion).
+    // Gaussian relevance never hits zero (no cliff, survives the score>0 filter,
+    // so a boost can always lift a low-ELO target), and the [0.5, 1] jitter keeps
+    // ELO ordering up to a 2× factor while still shuffling near-equal cards so the
+    // same cards don't loop every session. SIGMA=300 reproduces the old ramp's
+    // half-weight point (distance 250 → ~0.5), leaving center-of-range difficulty
+    // matching unchanged.
     //
     // Card ELO is read from the pooled `.elo` carried on each candidate by
     // getCardsCenteredAtELO — verified equal to a separate getCardEloData()
@@ -115,8 +136,8 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
       const cardElo = c.elo ?? 1000;
 
       const distance = Math.abs(cardElo - userGlobalElo);
-      const rawScore = Math.max(0, 1 - distance / 500);
-      const samplingKey = rawScore > 0 ? Math.random() ** (1 / rawScore) : 0;
+      const relevance = Math.exp(-((distance / ELO_RELEVANCE_SIGMA) ** 2));
+      const samplingKey = relevance * (0.5 + 0.5 * Math.random());
 
       return {
         cardId: c.cardID,
@@ -129,7 +150,7 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
             strategyId: this.strategyId || 'NAVIGATION_STRATEGY-ELO-default',
             action: 'generated',
             score: samplingKey,
-            reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), raw ${rawScore.toFixed(3)}, key ${samplingKey.toFixed(3)}`,
+            reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), relevance ${relevance.toFixed(3)}, key ${samplingKey.toFixed(3)}`,
           },
         ],
       };

package/src/study/SessionController.ts

@@ -21,7 +21,12 @@ import { mergeHints } from '@db/core/navigators/Pipeline';
 import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
 import { captureMixerRun } from './MixerDebugger';
 import { startSessionTracking, recordCardPresentation, snapshotQueues, endSessionTracking } from './SessionDebugger';
-import { registerActiveController, type SessionDebugSnapshot, type SessionQueueDebug } from './SessionOverlay';
+import {
+  registerActiveController,
+  type SessionDebugSnapshot,
+  type SessionDrawnCardDebug,
+  type SessionQueueDebug,
+} from './SessionOverlay';
 
 // ReplanHints is defined in generators/types to avoid circular dependencies.
 // Re-exported here for backward compatibility.
@@ -59,6 +64,21 @@ export interface ReplanOptions {
    * multiply, require/exclude lists concatenate).
    */
   sessionHints?: ReplanHints;
+  /**
+   * Like `sessionHints`, but *merged* into the existing session-durable hints
+   * (via `mergeHints`) instead of replacing them. Use when emphasis should
+   * *accumulate* across replans rather than clobber — e.g. introducing a second
+   * concept mid-session must not wipe the first concept's boost, nor any
+   * `difficultyBooster`/`conceptBackoff` state on other concepts.
+   *
+   * Merge semantics (see `mergeHints`): boosts MULTIPLY, require/exclude lists
+   * concat-dedup. Re-emphasising the *same* tag therefore compounds — callers
+   * boosting a tag they may have already boosted should clamp at the call site.
+   *
+   * If both `sessionHints` and `mergeSessionHints` are supplied, the replace is
+   * applied first, then the merge — but they are normally mutually exclusive.
+   */
+  mergeSessionHints?: ReplanHints;
   /**
    * Maximum number of new cards to return from the pipeline.
    * Default: 20 (the standard session batch size).
@@ -283,6 +303,22 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   private _sessionHints: ReplanHints | null = null;
 
+  /**
+   * Card IDs that have been *served* (drawn/consumed) this session. Populated
+   * at the single consumption choke-point (removeItemFromQueue), so it reflects
+   * a draw the instant it happens — earlier than `_sessionRecord`, which only
+   * lands once the card is *responded to*.
+   *
+   * Used to keep already-served cards out of newQ on every (re)plan: a `new`
+   * card shown once must never re-enter newQ this session. This is the general
+   * guard against re-presentation — including the case where a replan in flight
+   * captured a now-drawn card (e.g. a +INF require-injected follow-up the
+   * depletion prefetch grabbed just before it was drawn). Reviews/failed cards
+   * legitimately recur and are tracked by their own queues, so this only gates
+   * `new`-origin candidates.
+   */
+  private _servedCardIds: Set<string> = new Set();
+
   /**
    * Consumer-supplied hooks invoked after each question response is processed.
    * Seeded from constructor options (threaded from
@@ -562,6 +598,7 @@ export class SessionController<TView = unknown> extends Loggable {
     if (opts.mode && opts.mode !== 'replace') return true;
     if (opts.hints && Object.keys(opts.hints).length > 0) return true;
     if (opts.sessionHints !== undefined) return true;
+    if (opts.mergeSessionHints !== undefined) return true;
     return false;
   }
 
@@ -623,6 +660,14 @@ export class SessionController<TView = unknown> extends Loggable {
       );
     }
 
+    // Additive emphasis: merge (don't clobber) into durable hints. Lets a new
+    // concept's boost accumulate on top of prior concepts' boosts and any
+    // observer-managed boost/decay state. Boosts multiply, lists concat-dedup.
+    if (opts.mergeSessionHints !== undefined) {
+      this._sessionHints = mergeHints([this._sessionHints, opts.mergeSessionHints]) ?? null;
+      this.log(`[Replan] Session hints merged: ${JSON.stringify(this._sessionHints)}`);
+    }
+
     // Forward hints to all sources (CourseDB stashes them, Pipeline consumes
     // them). The one-shot `opts.hints` are merged with the durable
     // `_sessionHints` so session emphasis survives this and every later run.
@@ -692,6 +737,16 @@ export class SessionController<TView = unknown> extends Loggable {
       }
       return { length: q.length, dequeueCount: q.dequeueCount, cards };
     };
+    const drawnCards: SessionDrawnCardDebug[] = this._sessionRecord.map((r) => {
+      const last = r.records[r.records.length - 1];
+      return {
+        cardID: r.item.cardID,
+        status: r.item.status,
+        attempts: r.records.length,
+        correct: last && isQuestionRecord(last) ? last.isCorrect : null,
+        timeSpentMs: r.records.reduce((sum, rec) => sum + rec.timeSpent, 0),
+      };
+    });
     return {
       secondsRemaining: this.secondsRemaining,
       hasCardGuarantee: this.hasCardGuarantee,
@@ -704,6 +759,7 @@ export class SessionController<TView = unknown> extends Loggable {
       reviewQ: describe(this.reviewQ),
       newQ: describe(this.newQ),
       failedQ: describe(this.failedQ),
+      drawnCards,
     };
   }
 
@@ -1100,8 +1156,13 @@ export class SessionController<TView = unknown> extends Loggable {
     const reviewWeighted = mixedWeighted
       .filter((w) => getCardOrigin(w) === 'review')
       .slice(0, this._initialReviewCap);
+    // Proactive de-dup: a `new` card served earlier this session must never
+    // re-enter newQ — whether it slipped back via a +INF require-injection, an
+    // additive merge, or a stale generator candidate. This is the general guard
+    // (see _servedCardIds); it makes re-presentation structurally impossible
+    // rather than relying on each upstream path to exclude correctly.
     const newWeighted = mixedWeighted
-      .filter((w) => getCardOrigin(w) === 'new')
+      .filter((w) => getCardOrigin(w) === 'new' && !this._servedCardIds.has(w.cardId))
       .slice(0, newLimit);
 
     logger.debug(`[reviews] got ${reviewWeighted.length} reviews from mixer`);
@@ -1347,7 +1408,10 @@ export class SessionController<TView = unknown> extends Loggable {
         `Triggering background replan.`
       );
       // label is observability-only (overlay/logs); does not affect coalescing.
-      void this.requestReplan({ label: 'auto:depletion' });
+      // mode:'merge' preserves any already-queued cards (e.g. an undrawn
+      // prescribed WST whose one-shot requireCards won't be re-asserted by this
+      // bare replan) instead of replaceAll() wiping them. See mergeToFront.
+      void this.requestReplan({ label: 'auto:depletion', mode: 'merge' });
     }
 
     // Opportunistic quality: few well-indicated cards remain.
@@ -1586,6 +1650,21 @@ export class SessionController<TView = unknown> extends Loggable {
    * Remove an item from its source queue after consumption by nextCard().
    */
   private removeItemFromQueue(item: StudySessionItem): void {
+    // Durable-until-drawn requirements: a caller may place a card ID in the
+    // session-durable `requireCards` (via mergeSessionHints) so every later
+    // replan re-asserts it at +INF until it actually surfaces — e.g. a
+    // prescribed intro follow-up that must survive the replace-mode burst/auto
+    // replans that would otherwise clobber a one-shot requirement. The
+    // requirement is satisfied the instant the card is drawn, so clear it here
+    // (the single consumption choke-point) to stop it being re-injected forever
+    // and to bound accumulation. Generic: card-ID only, no domain vocabulary.
+    this._clearDurableRequirement(item.cardID);
+
+    // Record the draw immediately (earlier than _sessionRecord, which waits for
+    // a response) so getWeightedContent can keep this card out of newQ on any
+    // replan that lands after this draw.
+    this._servedCardIds.add(item.cardID);
+
     // Check each queue - item should be at the front of one of them
     if (this.reviewQ.peek(0)?.cardID === item.cardID) {
       this.reviewQ.dequeue((queueItem) => queueItem.cardID);
@@ -1599,6 +1678,28 @@ export class SessionController<TView = unknown> extends Loggable {
     }
   }
 
+  /**
+   * Remove a satisfied card ID from the durable session-hint `requireCards`
+   * list. Called when a card is consumed (see removeItemFromQueue). No-op if
+   * the card was not a durable requirement.
+   *
+   * Matches literal IDs only: a glob/pattern requirement (which may stand for
+   * several cards) is NOT considered satisfied by a single draw and is left in
+   * place — durable patterns are the caller's responsibility, one-shot `hints`
+   * remain the right tool for them.
+   */
+  private _clearDurableRequirement(cardID: string): void {
+    const req = this._sessionHints?.requireCards;
+    if (!req || req.length === 0) return;
+    const next = req.filter((id) => id !== cardID);
+    if (next.length === req.length) return; // not a durable requirement
+    this._sessionHints = {
+      ...this._sessionHints!,
+      requireCards: next.length > 0 ? next : undefined,
+    };
+    this.log(`[Replan] Durable requirement satisfied & cleared on draw: ${cardID}`);
+  }
+
   /**
    * End the session and record learning outcomes.
    *

package/src/study/SessionOverlay.ts

@@ -25,6 +25,22 @@ export interface SessionQueueDebug {
   cards: string[];
 }
 
+/**
+ * A card the learner has interacted with this session (one entry per card in
+ * the session record, regardless of which queue — if any — still holds it).
+ */
+export interface SessionDrawnCardDebug {
+  cardID: string;
+  /** Queue status at draw time: 'new' | 'review' | 'failed-new' | 'failed-review'. */
+  status: string;
+  /** Number of CardRecords logged for this card this session (≥1). */
+  attempts: number;
+  /** Latest record's correctness; null for non-question (info) records. */
+  correct: boolean | null;
+  /** Total time spent across all of this card's records, in ms. */
+  timeSpentMs: number;
+}
+
 /** Live snapshot of the controller, read fresh on each overlay tick. */
 export interface SessionDebugSnapshot {
   secondsRemaining: number;
@@ -42,6 +58,8 @@ export interface SessionDebugSnapshot {
   reviewQ: SessionQueueDebug;
   newQ: SessionQueueDebug;
   failedQ: SessionQueueDebug;
+  /** Every card the learner has interacted with this session, draw order. */
+  drawnCards: SessionDrawnCardDebug[];
 }
 
 /** The narrow surface the overlay needs from a SessionController. */
@@ -75,7 +93,11 @@ export function getActiveController(): SessionDebugTarget | null {
 
 const OVERLAY_ID = 'skuilder-session-overlay';
 const POLL_MS = 300;
-/** Queues with at most this many cards are listed outright; larger ones collapse to a count. */
+/**
+ * Cap on how many cards a queue lists by default. Queues at or below this show
+ * in full; larger ones show the first INLINE_THRESHOLD then a clickable
+ * "… +N more" affordance that expands to the full list (and back).
+ */
 const INLINE_THRESHOLD = 5;
 
 /** Braille spinner frames, advanced once per render tick (≈POLL_MS cadence). */
@@ -85,8 +107,29 @@ let spinnerFrame = 0;
 let overlayEl: HTMLElement | null = null;
 let pollHandle: ReturnType<typeof setInterval> | null = null;
 
-/** Expansion state for collapsible (large) queues, preserved across re-renders. */
-const expanded: Record<string, boolean> = { reviewQ: false, newQ: false, failedQ: false };
+/**
+ * Most recent snapshot rendered, retained so the click-to-copy button can
+ * serialise exactly what is on screen at click time (decoupled from the poll).
+ */
+let lastSnapshot: SessionDebugSnapshot | null = null;
+
+/** Epoch ms until which the copy button shows its "copied" confirmation. */
+let copyFlashUntil = 0;
+
+/**
+ * When minified, the overlay collapses to just its header bar (title + copy +
+ * restore button), suppressing all body sections. The poll keeps running so
+ * `lastSnapshot` — and therefore the copy button — stays current underneath.
+ */
+let minified = false;
+
+/** Expansion state for collapsible (large) lists, preserved across re-renders. */
+const expanded: Record<string, boolean> = {
+  reviewQ: false,
+  newQ: false,
+  failedQ: false,
+  drawn: false,
+};
 
 /**
  * Toggle the pinned overlay on/off. No-ops (with a console hint) when there is
@@ -107,6 +150,7 @@ export function toggleSessionOverlay(): void {
 }
 
 function mount(): void {
+  minified = false;
   overlayEl = document.createElement('div');
   overlayEl.id = OVERLAY_ID;
   Object.assign(overlayEl.style, {
@@ -149,11 +193,22 @@ function render(): void {
 
   const ctrl = getActiveController();
   if (!ctrl) {
-    overlayEl.innerHTML = headerHtml() + `<div style="opacity:.65">No active session.</div>`;
+    lastSnapshot = null;
+    overlayEl.innerHTML =
+      headerHtml() + (minified ? '' : `<div style="opacity:.65">No active session.</div>`);
+    attachHandlers();
     return;
   }
 
   const s = ctrl.getDebugSnapshot();
+  lastSnapshot = s;
+
+  if (minified) {
+    overlayEl.innerHTML = headerHtml();
+    attachHandlers();
+    return;
+  }
+
   overlayEl.innerHTML =
     headerHtml() +
     replanHtml(s) +
@@ -161,9 +216,17 @@ function render(): void {
     hintsHtml(s.sessionHints) +
     queueHtml('reviewQ', 'reviewQ', s.reviewQ) +
     queueHtml('newQ', 'newQ', s.newQ) +
-    queueHtml('failedQ', 'failedQ', s.failedQ);
+    queueHtml('failedQ', 'failedQ', s.failedQ) +
+    drawnHtml('drawn', s.drawnCards);
+
+  attachHandlers();
+}
+
+/** (Re-)bind click handlers after each innerHTML rewrite. */
+function attachHandlers(): void {
+  if (!overlayEl) return;
 
-  // Re-attach toggle handlers for collapsible queue headers each render.
+  // Toggle handlers for collapsible queue / drawn-list headers and footers.
   overlayEl.querySelectorAll<HTMLElement>('[data-q]').forEach((el) => {
     el.onclick = () => {
       const key = el.dataset.q;
@@ -172,10 +235,61 @@ function render(): void {
       render();
     };
   });
+
+  // Global click-to-copy: dump the currently-displayed snapshot as plain text.
+  const copyBtn = overlayEl.querySelector<HTMLElement>('[data-copy]');
+  if (copyBtn) {
+    copyBtn.onclick = (ev) => {
+      ev.stopPropagation();
+      copySnapshot();
+    };
+  }
+
+  // Minify / restore: collapse the overlay to its header bar and back.
+  const minBtn = overlayEl.querySelector<HTMLElement>('[data-min]');
+  if (minBtn) {
+    minBtn.onclick = (ev) => {
+      ev.stopPropagation();
+      minified = !minified;
+      render();
+    };
+  }
+}
+
+/** Serialise the on-screen snapshot to the clipboard, with a transient flash. */
+function copySnapshot(): void {
+  const text = snapshotToText(lastSnapshot);
+  const flash = () => {
+    copyFlashUntil = Date.now() + 1200;
+    render();
+  };
+  const clip = typeof navigator !== 'undefined' ? navigator.clipboard : undefined;
+  if (clip?.writeText) {
+    clip.writeText(text).then(flash, (err) => {
+      logger.warn(`[Session Overlay] Clipboard write failed: ${String(err)}`);
+    });
+  } else {
+    logger.info(`[Session Overlay] Clipboard unavailable; snapshot follows:\n${text}`);
+  }
 }
 
 function headerHtml(): string {
-  return `<div style="font-weight:600;color:#93c5fd;margin-bottom:4px">⚙ SessionController</div>`;
+  const flashing = Date.now() < copyFlashUntil;
+  const btnLabel = flashing ? '✓ copied' : '⎘ copy';
+  const btnColor = flashing ? '#86efac' : '#93c5fd';
+  const copyBtn =
+    `<span data-copy style="cursor:pointer;float:right;font-weight:400;` +
+    `color:${btnColor};border:1px solid currentColor;border-radius:4px;` +
+    `padding:0 4px;line-height:1.3">${btnLabel}</span>`;
+  const minBtn =
+    `<span data-min title="${minified ? 'Restore' : 'Minify'}" ` +
+    `style="cursor:pointer;float:right;font-weight:400;color:#93c5fd;` +
+    `border:1px solid currentColor;border-radius:4px;padding:0 5px;` +
+    `margin-right:4px;line-height:1.3">${minified ? '▢' : '—'}</span>`;
+  return (
+    `<div style="font-weight:600;color:#93c5fd;margin-bottom:${minified ? 0 : 4}px">` +
+    `${copyBtn}${minBtn}⚙ SessionController</div>`
+  );
 }
 
 function replanHtml(s: SessionDebugSnapshot): string {
@@ -238,29 +352,139 @@ function hintsHtml(h: ReplanHints | null): string {
 
 function queueHtml(key: string, label: string, q: SessionQueueDebug): string {
   const collapsible = q.length > INLINE_THRESHOLD;
-  const isOpen = !collapsible || expanded[key];
+  const isOpen = collapsible && expanded[key];
   const caret = collapsible ? (expanded[key] ? '▾ ' : '▸ ') : '';
   const drawn = q.dequeueCount ? ` <span style="opacity:.5">drawn ${q.dequeueCount}</span>` : '';
-  const titleStyle = collapsible
-    ? 'cursor:pointer;color:#f9a8d4'
-    : 'color:#f9a8d4';
+  const titleStyle = collapsible ? 'cursor:pointer;color:#f9a8d4' : 'color:#f9a8d4';
   const titleAttr = collapsible ? ` data-q="${key}"` : '';
   const title = `<div${titleAttr} style="${titleStyle}">${caret}${label}: ${q.length}${drawn}</div>`;
 
-  let body = '';
-  if (isOpen && q.cards.length) {
-    body =
-      `<ol style="margin:2px 0 6px 0;padding-left:20px">` +
-      q.cards.map((c) => `<li style="white-space:nowrap">${esc(c)}</li>`).join('') +
-      `</ol>`;
-  } else if (!q.cards.length) {
-    body = `<div style="margin:1px 0 6px 6px;opacity:.5">empty</div>`;
-  } else {
-    body = `<div style="margin:1px 0 6px 6px;opacity:.55">(${q.length} cards — click to expand)</div>`;
+  if (!q.cards.length) {
+    return title + `<div style="margin:1px 0 6px 6px;opacity:.5">empty</div>`;
   }
+
+  // Always list up to INLINE_THRESHOLD cards; the remainder hides behind an
+  // expand toggle so long queues never blow out the overlay but stay inspectable.
+  const shown = isOpen ? q.cards : q.cards.slice(0, INLINE_THRESHOLD);
+  const hiddenCount = q.length - shown.length;
+  const listMarginBottom = collapsible ? 2 : 6;
+
+  let body =
+    `<ol style="margin:2px 0 ${listMarginBottom}px 0;padding-left:20px">` +
+    shown.map((c) => `<li style="white-space:nowrap">${esc(c)}</li>`).join('') +
+    `</ol>`;
+
+  if (collapsible) {
+    const footer = isOpen ? '▾ show less' : `… +${hiddenCount} more`;
+    body += `<div data-q="${key}" style="cursor:pointer;margin:0 0 6px 20px;opacity:.6">${footer}</div>`;
+  }
+
   return title + body;
 }
 
+/** Compact, colour-coded per-card glyph: ✓ correct, ✗ wrong, · info-only. */
+function outcomeGlyph(correct: boolean | null): string {
+  if (correct === true) return `<span style="color:#86efac">✓</span>`;
+  if (correct === false) return `<span style="color:#fca5a5">✗</span>`;
+  return `<span style="opacity:.5">·</span>`;
+}
+
+/**
+ * Expandable list of every card the learner has interacted with this session.
+ * Mirrors `queueHtml`'s collapse behaviour but renders richer per-card detail
+ * (status, outcome, attempt count) since this is the audit trail, not a queue.
+ */
+function drawnHtml(key: string, drawn: SessionDrawnCardDebug[]): string {
+  const collapsible = drawn.length > INLINE_THRESHOLD;
+  const isOpen = collapsible && expanded[key];
+  const caret = collapsible ? (expanded[key] ? '▾ ' : '▸ ') : '';
+  const titleStyle = collapsible ? 'cursor:pointer;color:#c4b5fd' : 'color:#c4b5fd';
+  const titleAttr = collapsible ? ` data-q="${key}"` : '';
+  const title = `<div${titleAttr} style="${titleStyle}">${caret}drawn: ${drawn.length}</div>`;
+
+  if (!drawn.length) {
+    return title + `<div style="margin:1px 0 6px 6px;opacity:.5">none yet</div>`;
+  }
+
+  const shown = isOpen ? drawn : drawn.slice(0, INLINE_THRESHOLD);
+  const hiddenCount = drawn.length - shown.length;
+  const listMarginBottom = collapsible ? 2 : 6;
+
+  const rows = shown
+    .map((d) => {
+      const retries = d.attempts > 1 ? `<span style="opacity:.5"> ×${d.attempts}</span>` : '';
+      const time = `<span style="opacity:.45"> ${Math.round(d.timeSpentMs / 100) / 10}s</span>`;
+      return (
+        `<li style="white-space:nowrap">${outcomeGlyph(d.correct)} ${esc(d.cardID)}` +
+        `<span style="opacity:.5"> [${esc(d.status)}]</span>${retries}${time}</li>`
+      );
+    })
+    .join('');
+
+  let body = `<ol style="margin:2px 0 ${listMarginBottom}px 0;padding-left:20px">${rows}</ol>`;
+
+  if (collapsible) {
+    const footer = isOpen ? '▾ show less' : `… +${hiddenCount} more`;
+    body += `<div data-q="${key}" style="cursor:pointer;margin:0 0 6px 20px;opacity:.6">${footer}</div>`;
+  }
+
+  return title + body;
+}
+
+/**
+ * Plain-text rendering of a snapshot for the clipboard. Mirrors the on-screen
+ * sections (without truncation) so a copied dump is a complete, paste-able
+ * picture of session state at the moment of the click.
+ */
+function snapshotToText(s: SessionDebugSnapshot | null): string {
+  if (!s) return 'SessionController — no active session.';
+
+  const lines: string[] = [];
+  lines.push('=== SessionController ===');
+  lines.push(`time ${formatTime(s.secondsRemaining)}`);
+  if (s.hasCardGuarantee) lines.push(`guarantee: ${s.minCardsGuarantee}`);
+  lines.push(`well-indicated left: ${s.wellIndicatedRemaining}`);
+  lines.push(`current: ${s.currentCard ?? '—'}`);
+  lines.push(
+    s.replanActive ? `replan: ACTIVE [${s.replanLabel ?? '(auto)'}]` : 'replan: idle'
+  );
+
+  lines.push('');
+  lines.push('sessionHints:');
+  const h = s.sessionHints;
+  const hintParts: string[] = [];
+  if (h) {
+    if (h.boostTags && Object.keys(h.boostTags).length)
+      hintParts.push(`  boost: ${Object.entries(h.boostTags).map(([k, v]) => `${k}×${v}`).join(', ')}`);
+    if (h.boostCards && Object.keys(h.boostCards).length)
+      hintParts.push(`  boostCards: ${Object.entries(h.boostCards).map(([k, v]) => `${k}×${v}`).join(', ')}`);
+    if (h.requireCards?.length) hintParts.push(`  require: ${h.requireCards.join(', ')}`);
+    if (h.requireTags?.length) hintParts.push(`  requireTags: ${h.requireTags.join(', ')}`);
+    if (h.excludeTags?.length) hintParts.push(`  exclude: ${h.excludeTags.join(', ')}`);
+    if (h.excludeCards?.length) hintParts.push(`  excludeCards: ${h.excludeCards.join(', ')}`);
+  }
+  lines.push(hintParts.length ? hintParts.join('\n') : '  none');
+
+  const queueText = (label: string, q: SessionQueueDebug) => {
+    lines.push('');
+    lines.push(`${label}: ${q.length} (drawn ${q.dequeueCount})`);
+    q.cards.forEach((c, i) => lines.push(`  ${i + 1}. ${c}`));
+  };
+  queueText('reviewQ', s.reviewQ);
+  queueText('newQ', s.newQ);
+  queueText('failedQ', s.failedQ);
+
+  lines.push('');
+  lines.push(`drawn: ${s.drawnCards.length}`);
+  s.drawnCards.forEach((d, i) => {
+    const mark = d.correct === true ? '✓' : d.correct === false ? '✗' : '·';
+    const time = `${Math.round(d.timeSpentMs / 100) / 10}s`;
+    lines.push(`  ${i + 1}. ${mark} ${d.cardID} [${d.status}] ×${d.attempts} ${time}`);
+  });
+
+  return lines.join('\n');
+}
+
 function formatTime(totalSeconds: number): string {
   const s = Math.max(0, Math.round(totalSeconds));
   const m = Math.floor(s / 60);