@vue-skuilder/db 0.2.4 → 0.2.7

package/src/study/ItemQueue.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { ItemQueue } from './ItemQueue';
+
+type Item = { cardID: string };
+const id = (i: Item) => i.cardID;
+const item = (cardID: string): Item => ({ cardID });
+const ids = (q: ItemQueue<Item>): string[] =>
+  Array.from({ length: q.length }, (_, i) => q.peek(i).cardID);
+
+describe('ItemQueue.mergeToFront', () => {
+  it('adds new items to the front, preserving batch order', () => {
+    const q = new ItemQueue<Item>();
+    q.addAll([item('a'), item('b')], id);
+
+    const added = q.mergeToFront([item('x'), item('y')], id);
+
+    expect(added).toBe(2);
+    expect(ids(q)).toEqual(['x', 'y', 'a', 'b']);
+  });
+
+  it('skips an ordinary duplicate, leaving it in place', () => {
+    const q = new ItemQueue<Item>();
+    q.addAll([item('a'), item('b'), item('c')], id);
+
+    // 'b' already queued and not mandatory → left where it is; 'x' fronted.
+    const added = q.mergeToFront([item('x'), item('b')], id);
+
+    expect(added).toBe(1);
+    expect(ids(q)).toEqual(['x', 'a', 'b', 'c']);
+  });
+
+  it('re-fronts an already-queued mandatory card instead of burying it', () => {
+    // Repro of the require-card burial: 'req' was fronted by a prior burst
+    // replan, then an additive merge brings fresh non-required cards. Without
+    // the mandatory re-front, 'x'/'y' would leapfrog 'req' and sink it.
+    const q = new ItemQueue<Item>();
+    q.addAll([item('req'), item('a'), item('b')], id);
+
+    const added = q.mergeToFront(
+      [item('req'), item('x'), item('y')],
+      id,
+      new Set(['req'])
+    );
+
+    // 'req' is not a *new* add, so it isn't counted...
+    expect(added).toBe(2);
+    // ...but it leads the queue (ahead of the freshly merged 'x'/'y').
+    expect(ids(q)).toEqual(['req', 'x', 'y', 'a', 'b']);
+    // and isn't duplicated.
+    expect(ids(q).filter((c) => c === 'req')).toHaveLength(1);
+  });
+
+  it('keeps a mandatory card already at the front at the front', () => {
+    const q = new ItemQueue<Item>();
+    q.addAll([item('req'), item('a')], id);
+
+    q.mergeToFront([item('req'), item('x')], id, new Set(['req']));
+
+    expect(ids(q)).toEqual(['req', 'x', 'a']);
+  });
+
+  it('without forceFrontIds, preserves the legacy skip-duplicate behavior', () => {
+    const q = new ItemQueue<Item>();
+    q.addAll([item('req'), item('a')], id);
+
+    // No mandatory set → 'req' stays put and is buried behind the merged 'x'.
+    q.mergeToFront([item('req'), item('x')], id);
+
+    expect(ids(q)).toEqual(['x', 'req', 'a']);
+  });
+});

package/src/study/ItemQueue.ts

@@ -73,8 +73,21 @@ export class ItemQueue<T> {
    * Merge new items into the front of the queue, skipping duplicates.
    * Used by additive replans to inject high-quality candidates without
    * discarding the existing queue contents.
+   *
+   * `forceFrontIds` carries the mandatory (`+INF`) cards in this batch — a
+   * durable `requireCard`/`requireTag` re-asserted by every replan. An ordinary
+   * duplicate is left in place (skip), but a mandatory one that's *already*
+   * queued is pulled out of its current slot so it rejoins at the front in batch
+   * order. Without this, an additive merge unshifts fresh non-required cards
+   * ahead of an already-present required card, steadily burying it until it never
+   * gets drawn — defeating the "must appear" guarantee. Returns the count of
+   * genuinely new cards added (re-fronted duplicates are not counted).
    */
-  public mergeToFront(items: T[], cardIdExtractor: (item: T) => string): number {
+  public mergeToFront(
+    items: T[],
+    cardIdExtractor: (item: T) => string,
+    forceFrontIds?: ReadonlySet<string>
+  ): number {
     let added = 0;
     const toInsert: T[] = [];
     for (const item of items) {
@@ -83,6 +96,11 @@ export class ItemQueue<T> {
         this.seenCardIds.push(cardId);
         toInsert.push(item);
         added++;
+      } else if (forceFrontIds?.has(cardId)) {
+        const idx = this.q.findIndex((qi) => cardIdExtractor(qi) === cardId);
+        if (idx >= 0) {
+          toInsert.push(...this.q.splice(idx, 1));
+        }
       }
     }
     this.q.unshift(...toInsert);

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,9 +1156,27 @@ export class SessionController<TView = unknown> extends Loggable {
     const reviewWeighted = mixedWeighted
       .filter((w) => getCardOrigin(w) === 'review')
       .slice(0, this._initialReviewCap);
-    const newWeighted = mixedWeighted
-      .filter((w) => getCardOrigin(w) === 'new')
-      .slice(0, newLimit);
+    // 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 newCandidates = mixedWeighted.filter(
+      (w) => getCardOrigin(w) === 'new' && !this._servedCardIds.has(w.cardId)
+    );
+    // `+INF` is the hard "include at all costs" sentinel applied by require*
+    // injection (see Pipeline.applyRequirement). Partition these mandatory cards
+    // to the front and exempt them from the newLimit slice, so neither the
+    // mixer's source-shuffle/round-robin nor the cap can bury or drop a required
+    // card before it reaches newQ. The set is also handed to mergeToFront so an
+    // already-queued required card gets re-fronted rather than leapfrogged.
+    const mandatoryWeighted = newCandidates.filter((w) => w.score === Number.POSITIVE_INFINITY);
+    const optionalWeighted = newCandidates.filter((w) => w.score !== Number.POSITIVE_INFINITY);
+    const newWeighted = [
+      ...mandatoryWeighted,
+      ...optionalWeighted.slice(0, Math.max(0, newLimit - mandatoryWeighted.length)),
+    ];
+    const mandatoryIds = new Set(mandatoryWeighted.map((w) => w.cardId));
 
     logger.debug(`[reviews] got ${reviewWeighted.length} reviews from mixer`);
 
@@ -1145,8 +1219,10 @@ export class SessionController<TView = unknown> extends Loggable {
     }
 
     if (additive) {
-      // Additive replan: merge new candidates into front of existing queue
-      const added = this.newQ.mergeToFront(newItems, (item) => item.cardID);
+      // Additive replan: merge new candidates into front of existing queue.
+      // Pass mandatory (+INF) ids so an already-queued required card is pulled
+      // back to the front instead of being buried by fresh non-required cards.
+      const added = this.newQ.mergeToFront(newItems, (item) => item.cardID, mandatoryIds);
       report += `Additive merge: ${added} new cards added to front of newQ\n`;
     } else if (replan) {
       // Atomic swap: replace entire newQ contents at once (no empty-queue window)
@@ -1347,7 +1423,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 +1665,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 +1693,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);