@vue-skuilder/db 0.2.3 → 0.2.4

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.3",
+  "version": "0.2.4",
   "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.3",
+    "@vue-skuilder/common": "0.2.4",
     "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.3"
+  "stableVersion": "0.2.4"
 }

package/src/study/SessionController.ts

@@ -21,6 +21,7 @@ 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';
 
 // ReplanHints is defined in generators/types to avoid circular dependencies.
 // Re-exported here for backward compatibility.
@@ -236,6 +237,14 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   private _replanPromise: Promise<void> | null = null;
 
+  /**
+   * Reason for the replan currently executing in `_runReplan`, surfaced by the
+   * debug overlay's spinner. The caller's `opts.label` when present, else
+   * `'(auto)'`. Only meaningful while `_replanPromise` is non-null; cleared
+   * when the in-flight chain settles.
+   */
+  private _activeReplanLabel: string | null = null;
+
   /**
    * Number of well-indicated new cards remaining before the queue
    * degrades to poorly-indicated content. Decremented on each newQ
@@ -372,6 +381,11 @@ export class SessionController<TView = unknown> extends Loggable {
     endTime: ${this.endTime}
     defaultBatchLimit: ${this._defaultBatchLimit}
     initialReviewCap: ${this._initialReviewCap}`);
+
+    // Expose this (now the most-recently-constructed) controller to the debug
+    // overlay (window.skuilder.session.dbgOverlay()). A new session overwrites
+    // the prior handle; no-op overhead when the overlay is never opened.
+    registerActiveController(this);
   }
 
   private tick() {
@@ -500,17 +514,33 @@ export class SessionController<TView = unknown> extends Loggable {
         .catch(() => undefined)
         .then(() => this._runReplan(opts));
 
-      this._replanPromise = queued.finally(() => {
-        if (this._replanPromise === queued) this._replanPromise = null;
+      // Compare against the promise we actually store. `.finally()` returns a
+      // NEW promise, so guarding on `=== queued` (the pre-finally promise) never
+      // matches and would leak _replanPromise. `tracked` is read only inside the
+      // async callback (after init), so the self-reference is safe.
+      const tracked: Promise<void> = queued.finally(() => {
+        if (this._replanPromise === tracked) {
+          this._replanPromise = null;
+          this._activeReplanLabel = null;
+        }
       });
+      this._replanPromise = tracked;
 
       return queued;
     }
 
     const run = this._runReplan(opts);
-    this._replanPromise = run.finally(() => {
-      if (this._replanPromise === run) this._replanPromise = null;
+    // Compare against the wrapped promise we store, not `run` — `.finally()`
+    // returns a new promise, so `=== run` never matches and _replanPromise
+    // would never clear (perpetual "replan in progress"). Safe self-reference:
+    // `tracked` is read only in the async callback, after initialization.
+    const tracked: Promise<void> = run.finally(() => {
+      if (this._replanPromise === tracked) {
+        this._replanPromise = null;
+        this._activeReplanLabel = null;
+      }
     });
+    this._replanPromise = tracked;
 
     await run;
   }
@@ -521,7 +551,12 @@ export class SessionController<TView = unknown> extends Loggable {
    * triggers in nextCard) return false and may coalesce.
    */
   private _replanHasIntent(opts: ReplanOptions): boolean {
-    if (opts.label) return true;
+    // NOTE: `label` is intentionally NOT an intent signal. It is observability-
+    // only metadata (debug overlay spinner, log tags, Pipeline strategy names),
+    // so labelling a replan must never change scheduling. Intent is strictly
+    // "does this replan carry scheduling-relevant options". This lets the
+    // unlabeled-but-named auto-replans (auto:depletion / auto:quality) keep
+    // coalescing while still showing a reason in the overlay.
     if (opts.limit !== undefined) return true;
     if (opts.minFollowUpCards !== undefined) return true;
     if (opts.mode && opts.mode !== 'replace') return true;
@@ -543,6 +578,11 @@ export class SessionController<TView = unknown> extends Loggable {
    * newQ.peek(0) is the imminent draw we need to exclude.
    */
   private async _runReplan(opts: ReplanOptions): Promise<void> {
+    // Surface the executing replan's reason to the debug overlay spinner.
+    // `label` is observability-only (see _replanHasIntent); '(auto)' covers any
+    // unlabeled path.
+    this._activeReplanLabel = opts.label ?? '(auto)';
+
     // Exclude all cards already presented this session. The pipeline may
     // not yet see their encounter records (async writes), so without this
     // they can re-enter newQ via replaceAll and cause duplicates.
@@ -638,6 +678,35 @@ export class SessionController<TView = unknown> extends Loggable {
     return this._sessionHints;
   }
 
+  /**
+   * Live state snapshot for the debug overlay (window.skuilder.session
+   * .dbgOverlay()). Reads directly from the private queues and hints, so it
+   * always reflects the current moment — unlike the passive SessionDebugger
+   * snapshots, which only capture what was explicitly pushed to them.
+   */
+  public getDebugSnapshot(): SessionDebugSnapshot {
+    const describe = <T extends { cardID: string }>(q: ItemQueue<T>): SessionQueueDebug => {
+      const cards: string[] = [];
+      for (let i = 0; i < q.length; i++) {
+        cards.push(q.peek(i).cardID);
+      }
+      return { length: q.length, dequeueCount: q.dequeueCount, cards };
+    };
+    return {
+      secondsRemaining: this.secondsRemaining,
+      hasCardGuarantee: this.hasCardGuarantee,
+      minCardsGuarantee: this._minCardsGuarantee,
+      wellIndicatedRemaining: this._wellIndicatedRemaining,
+      currentCard: this._currentCard?.item.cardID ?? null,
+      sessionHints: this._sessionHints,
+      replanActive: this._replanPromise !== null,
+      replanLabel: this._activeReplanLabel,
+      reviewQ: describe(this.reviewQ),
+      newQ: describe(this.newQ),
+      failedQ: describe(this.failedQ),
+    };
+  }
+
   /**
    * Merge `hints` into the durable session hints via the pipeline's
    * `mergeHints` (boosts multiply, require/exclude lists concat-dedup).
@@ -734,9 +803,14 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   private async _replanUncoalesced(opts: ReplanOptions): Promise<void> {
     const run = this._runReplan(opts);
-    this._replanPromise = run.finally(() => {
-      if (this._replanPromise === run) this._replanPromise = null;
+    // See requestReplan: guard against the wrapped promise we store, not `run`.
+    const tracked: Promise<void> = run.finally(() => {
+      if (this._replanPromise === tracked) {
+        this._replanPromise = null;
+        this._activeReplanLabel = null;
+      }
     });
+    this._replanPromise = tracked;
     await run;
   }
 
@@ -1272,7 +1346,8 @@ export class SessionController<TView = unknown> extends Loggable {
         `(${otherContent} in other queues) with ${this._secondsRemaining}s remaining. ` +
         `Triggering background replan.`
       );
-      void this.requestReplan();
+      // label is observability-only (overlay/logs); does not affect coalescing.
+      void this.requestReplan({ label: 'auto:depletion' });
     }
 
     // Opportunistic quality: few well-indicated cards remain.
@@ -1288,7 +1363,8 @@ export class SessionController<TView = unknown> extends Loggable {
         `[AutoReplan:quality] ${this._wellIndicatedRemaining} well-indicated cards remaining ` +
         `(newQ: ${this.newQ.length}). Triggering background replan.`
       );
-      void this.requestReplan();
+      // label is observability-only (overlay/logs); does not affect coalescing.
+      void this.requestReplan({ label: 'auto:quality' });
     }
 
     if (this._secondsRemaining <= 0 && this.failedQ.length === 0 && this._minCardsGuarantee <= 0) {

package/src/study/SessionDebugger.ts

@@ -1,5 +1,6 @@
 import { logger } from '../util/logger';
 import { clearRunHistory as clearPipelineRunHistory } from '../core/navigators/PipelineDebugger';
+import { toggleSessionOverlay } from './SessionOverlay';
 
 // ============================================================================
 // SESSION DEBUGGER
@@ -344,6 +345,14 @@ export const sessionDebugAPI = {
     showCurrentQueue();
   },
 
+  /**
+   * Toggle the pinned, live-updating DOM overlay for the active controller
+   * (queues, session hints, timer). No-ops in non-browser hosts.
+   */
+  dbgOverlay(): void {
+    toggleSessionOverlay();
+  },
+
   /**
    * Show presentation history for current or past session.
    */
@@ -413,6 +422,7 @@ export const sessionDebugAPI = {
 🎯 Session Debug API
 
 Commands:
+  .dbgOverlay()             Toggle the pinned live overlay (queues, hints, timer)
   .showQueue()              Show current queue state (active session only)
   .showHistory(index?)      Show presentation history (0=current/last, 1=previous, etc)
   .showInterleaving(index?) Analyze course interleaving pattern

package/src/study/SessionOverlay.ts

@@ -0,0 +1,276 @@
+import { logger } from '../util/logger';
+import type { ReplanHints } from '@db/core/navigators/generators/types';
+
+// ============================================================================
+// SESSION OVERLAY
+// ============================================================================
+//
+// A pinned, vanilla-DOM debug overlay for the LIVE SessionController. Unlike
+// `SessionDebugger` (a passive tracker of pushed snapshots), this reads the
+// active controller directly each tick — current queues, session hints, timer.
+//
+// Toggled via `window.skuilder.session.dbgOverlay()`.
+//
+// The `db` package is framework-agnostic, so this renders with raw DOM and
+// no-ops gracefully in non-browser hosts (e.g. the tuilder TUI). It is the
+// first DOM-rendering debug util in the package — kept self-contained here.
+//
+// ============================================================================
+
+/** Per-queue debug view: total length, cumulative draws, and head-first cardIDs. */
+export interface SessionQueueDebug {
+  length: number;
+  dequeueCount: number;
+  /** cardIDs in queue order, head (next draw) first. */
+  cards: string[];
+}
+
+/** Live snapshot of the controller, read fresh on each overlay tick. */
+export interface SessionDebugSnapshot {
+  secondsRemaining: number;
+  hasCardGuarantee: boolean;
+  minCardsGuarantee: number;
+  wellIndicatedRemaining: number;
+  /** cardID of the card currently in front of the learner, if any. */
+  currentCard: string | null;
+  /** Session-durable hints re-merged into every pipeline run this session. */
+  sessionHints: ReplanHints | null;
+  /** True while a replan is executing (in-flight). */
+  replanActive: boolean;
+  /** Reason for the in-flight replan (caller label, or '(auto)'); may be stale when idle. */
+  replanLabel: string | null;
+  reviewQ: SessionQueueDebug;
+  newQ: SessionQueueDebug;
+  failedQ: SessionQueueDebug;
+}
+
+/** The narrow surface the overlay needs from a SessionController. */
+export interface SessionDebugTarget {
+  getDebugSnapshot(): SessionDebugSnapshot;
+}
+
+// ----------------------------------------------------------------------------
+// Active-controller registry
+// ----------------------------------------------------------------------------
+//
+// The controller registers itself on construction; a new session overwrites the
+// prior handle. Kept here (a leaf module) so SessionController can import the
+// registrar without pulling in the overlay's DOM code or risking an import
+// cycle with SessionDebugger.
+
+let activeController: SessionDebugTarget | null = null;
+
+/** Called by SessionController's constructor. Pass `null` to deregister. */
+export function registerActiveController(controller: SessionDebugTarget | null): void {
+  activeController = controller;
+}
+
+export function getActiveController(): SessionDebugTarget | null {
+  return activeController;
+}
+
+// ----------------------------------------------------------------------------
+// Overlay rendering (vanilla DOM)
+// ----------------------------------------------------------------------------
+
+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. */
+const INLINE_THRESHOLD = 5;
+
+/** Braille spinner frames, advanced once per render tick (≈POLL_MS cadence). */
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+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 };
+
+/**
+ * Toggle the pinned overlay on/off. No-ops (with a console hint) when there is
+ * no DOM, so it is safe to call from any host environment.
+ */
+export function toggleSessionOverlay(): void {
+  if (typeof document === 'undefined') {
+    logger.info('[Session Overlay] No DOM available (non-browser host); overlay unavailable.');
+    return;
+  }
+  if (overlayEl) {
+    teardown();
+    logger.info('[Session Overlay] Hidden.');
+  } else {
+    mount();
+    logger.info('[Session Overlay] Shown. Toggle off with window.skuilder.session.dbgOverlay().');
+  }
+}
+
+function mount(): void {
+  overlayEl = document.createElement('div');
+  overlayEl.id = OVERLAY_ID;
+  Object.assign(overlayEl.style, {
+    position: 'fixed',
+    top: '8px',
+    left: '8px',
+    zIndex: '2147483647',
+    maxWidth: '320px',
+    maxHeight: '90vh',
+    overflowY: 'auto',
+    padding: '8px 10px',
+    background: 'rgba(17, 24, 39, 0.92)',
+    color: '#e5e7eb',
+    font: '11px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace',
+    borderRadius: '6px',
+    boxShadow: '0 4px 16px rgba(0,0,0,0.4)',
+    pointerEvents: 'auto',
+    userSelect: 'none',
+  });
+  document.body.appendChild(overlayEl);
+  render();
+  pollHandle = setInterval(render, POLL_MS);
+}
+
+function teardown(): void {
+  if (pollHandle !== null) {
+    clearInterval(pollHandle);
+    pollHandle = null;
+  }
+  if (overlayEl?.parentNode) {
+    overlayEl.parentNode.removeChild(overlayEl);
+  }
+  overlayEl = null;
+}
+
+function render(): void {
+  if (!overlayEl) return;
+
+  spinnerFrame++;
+
+  const ctrl = getActiveController();
+  if (!ctrl) {
+    overlayEl.innerHTML = headerHtml() + `<div style="opacity:.65">No active session.</div>`;
+    return;
+  }
+
+  const s = ctrl.getDebugSnapshot();
+  overlayEl.innerHTML =
+    headerHtml() +
+    replanHtml(s) +
+    metaHtml(s) +
+    hintsHtml(s.sessionHints) +
+    queueHtml('reviewQ', 'reviewQ', s.reviewQ) +
+    queueHtml('newQ', 'newQ', s.newQ) +
+    queueHtml('failedQ', 'failedQ', s.failedQ);
+
+  // Re-attach toggle handlers for collapsible queue headers each render.
+  overlayEl.querySelectorAll<HTMLElement>('[data-q]').forEach((el) => {
+    el.onclick = () => {
+      const key = el.dataset.q;
+      if (!key) return;
+      expanded[key] = !expanded[key];
+      render();
+    };
+  });
+}
+
+function headerHtml(): string {
+  return `<div style="font-weight:600;color:#93c5fd;margin-bottom:4px">⚙ SessionController</div>`;
+}
+
+function replanHtml(s: SessionDebugSnapshot): string {
+  if (!s.replanActive) {
+    return `<div style="margin-bottom:6px;opacity:.45">○ idle</div>`;
+  }
+  const frame = SPINNER_FRAMES[spinnerFrame % SPINNER_FRAMES.length];
+  const reason = esc(s.replanLabel ?? '(auto)');
+  return (
+    `<div style="margin-bottom:6px;color:#fde047">` +
+    `${frame} replanning <span style="opacity:.85">[${reason}]</span></div>`
+  );
+}
+
+function metaHtml(s: SessionDebugSnapshot): string {
+  const mmss = formatTime(s.secondsRemaining);
+  const guarantee = s.hasCardGuarantee
+    ? ` · <span style="color:#fbbf24">guarantee ${s.minCardsGuarantee}</span>`
+    : '';
+  const rows = [
+    `time ${mmss}${guarantee}`,
+    `well-indicated left: ${s.wellIndicatedRemaining}`,
+    `current: ${s.currentCard ? esc(s.currentCard) : '<span style="opacity:.6">—</span>'}`,
+  ];
+  return `<div style="margin-bottom:6px">${rows.map((r) => `<div>${r}</div>`).join('')}</div>`;
+}
+
+function hintsHtml(h: ReplanHints | null): string {
+  const parts: string[] = [];
+  if (h) {
+    if (h.boostTags && Object.keys(h.boostTags).length) {
+      parts.push(
+        `boost: ` +
+          Object.entries(h.boostTags)
+            .map(([k, v]) => `${esc(k)}<span style="opacity:.6">×${v}</span>`)
+            .join(', ')
+      );
+    }
+    if (h.boostCards && Object.keys(h.boostCards).length) {
+      parts.push(
+        `boostCards: ` +
+          Object.entries(h.boostCards)
+            .map(([k, v]) => `${esc(k)}<span style="opacity:.6">×${v}</span>`)
+            .join(', ')
+      );
+    }
+    if (h.requireCards?.length) parts.push(`require: ${h.requireCards.map(esc).join(', ')}`);
+    if (h.requireTags?.length) parts.push(`requireTags: ${h.requireTags.map(esc).join(', ')}`);
+    if (h.excludeTags?.length) parts.push(`exclude: ${h.excludeTags.map(esc).join(', ')}`);
+    if (h.excludeCards?.length) parts.push(`excludeCards: ${h.excludeCards.map(esc).join(', ')}`);
+  }
+  const body = parts.length
+    ? parts.map((p) => `<div style="margin-left:6px">${p}</div>`).join('')
+    : `<div style="margin-left:6px;opacity:.6">none</div>`;
+  return (
+    `<div style="margin-bottom:6px">` +
+    `<div style="color:#86efac">sessionHints</div>${body}</div>`
+  );
+}
+
+function queueHtml(key: string, label: string, q: SessionQueueDebug): string {
+  const collapsible = q.length > INLINE_THRESHOLD;
+  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 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>`;
+  }
+  return title + body;
+}
+
+function formatTime(totalSeconds: number): string {
+  const s = Math.max(0, Math.round(totalSeconds));
+  const m = Math.floor(s / 60);
+  const r = s % 60;
+  return `${m}:${r.toString().padStart(2, '0')}`;
+}
+
+function esc(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}