tessera-learn 0.0.13 → 0.2.0

package/src/runtime/App.svelte

@@ -10,6 +10,8 @@
   import DefaultLayout from '../components/DefaultLayout.svelte';
   import { NavigationState } from './navigation.svelte.js';
   import { ProgressState } from './progress.svelte.js';
+  import { DEFAULT_PASSING_SCORE } from './defaults.js';
+  import { applyBranding } from './branding.js';
   import { DurationTracker } from './duration.js';
   import { createAdapter } from 'virtual:tessera-adapter';
   import { buildXAPIClient } from 'virtual:tessera-xapi-setup';
@@ -39,7 +41,11 @@
   const auditMode =
     typeof window !== 'undefined' &&
     new URLSearchParams(window.location.search).has('__tessera_audit');
-  const progress = new ProgressState(gradedQuizIndices);
+  const progress = new ProgressState(
+    gradedQuizIndices,
+    config,
+    manifest.totalPages,
+  );
   const nav = new NavigationState(manifest, progress, config, auditMode);
   nav.setPageModules(pageModules);
   let duration = $state(new DurationTracker(0));
@@ -62,7 +68,7 @@
   // ---- Page context (reactive, read by Quiz in Step 8) ----
   let pageContext = $state({
     quiz: null,
-    passingScore: config.scoring?.passingScore ?? 70,
+    passingScore: config.scoring?.passingScore ?? DEFAULT_PASSING_SCORE,
   });
   setContext(TESSERA_PAGE, pageContext);
 
@@ -141,8 +147,6 @@
         ) {
           progress.markCompleteManually();
         }
-        progress.recalculateCompletion(manifest.totalPages, config);
-        progress.recalculateSuccess(config);
         onIdle(() => nav.prefetch(index + 1));
       })
       .catch((err) => {
@@ -165,96 +169,10 @@
     retryKey++;
   }
 
-  // ---- Branding ----
-  // Two sentinels so the validity check doesn't false-positive when the
-  // input happens to normalize to the initial fillStyle ("#000000").
-  function parseColor(color) {
-    if (
-      typeof CSS !== 'undefined' &&
-      CSS.supports &&
-      !CSS.supports('color', color)
-    ) {
-      return null;
-    }
-    const ctx = document.createElement('canvas').getContext('2d');
-    if (!ctx) return null;
-    ctx.fillStyle = '#000';
-    ctx.fillStyle = color;
-    const onBlack = ctx.fillStyle;
-    ctx.fillStyle = '#fff';
-    ctx.fillStyle = color;
-    const onWhite = ctx.fillStyle;
-    if (onBlack !== onWhite) return null;
-    const hex = String(onBlack).match(
-      /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i,
-    );
-    if (hex)
-      return {
-        r: parseInt(hex[1], 16),
-        g: parseInt(hex[2], 16),
-        b: parseInt(hex[3], 16),
-      };
-    const rgba = String(onBlack).match(
-      /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/,
-    );
-    return rgba ? { r: +rgba[1], g: +rgba[2], b: +rgba[3] } : null;
-  }
-
-  function rgbToHsl(r, g, b) {
-    r /= 255;
-    g /= 255;
-    b /= 255;
-    const max = Math.max(r, g, b),
-      min = Math.min(r, g, b);
-    let h = 0,
-      s = 0,
-      l = (max + min) / 2;
-    if (max !== min) {
-      const d = max - min;
-      s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
-      if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
-      else if (max === g) h = ((b - r) / d + 2) / 6;
-      else h = ((r - g) / d + 4) / 6;
-    }
-    return {
-      h: Math.round(h * 360),
-      s: Math.round(s * 100),
-      l: Math.round(l * 100),
-    };
-  }
-
-  function applyBranding(cfg) {
-    const el = document.documentElement;
-    if (cfg.branding?.primaryColor) {
-      el.style.setProperty('--tessera-primary', cfg.branding.primaryColor);
-      const rgb = parseColor(cfg.branding.primaryColor);
-      if (rgb) {
-        const hsl = rgbToHsl(rgb.r, rgb.g, rgb.b);
-        el.style.setProperty(
-          '--tessera-primary-light',
-          `hsl(${hsl.h}, ${Math.min(hsl.s + 10, 100)}%, 90%)`,
-        );
-        el.style.setProperty(
-          '--tessera-primary-dark',
-          `hsl(${hsl.h}, ${Math.min(hsl.s + 10, 100)}%, ${Math.max(hsl.l - 15, 10)}%)`,
-        );
-        el.style.setProperty(
-          '--tessera-focus-ring',
-          `0 0 0 3px rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, 0.4)`,
-        );
-      }
-    }
-    if (cfg.branding?.fontFamily) {
-      el.style.setProperty('--tessera-font-family', cfg.branding.fontFamily);
-    }
-  }
-
   function handleQuizComplete(e) {
     const { score } = e.detail;
     const pageIndex = nav.currentPageIndex;
     progress.quizCompleted(pageIndex, score);
-    progress.recalculateCompletion(manifest.totalPages, config);
-    progress.recalculateSuccess(config);
   }
 
   // ---- Persistence: serialize / restore ----
@@ -323,13 +241,9 @@
     }
     // Restore duration
     duration = new DurationTracker(saved.d || 0);
-    // Must come before recalc so manual-mode branches see the latch.
     if (saved.m === 1) {
       progress.markCompleteManually();
     }
-    // Recalculate derived state
-    progress.recalculateCompletion(manifest.totalPages, config);
-    progress.recalculateSuccess(config);
     // Navigate to bookmark (after state is restored so locking is correct)
     if (saved.b > 0 && saved.b < manifest.totalPages) {
       nav.goToPage(saved.b);
@@ -445,7 +359,7 @@
 
   // ---- Lifecycle ----
   onMount(async () => {
-    applyBranding(config);
+    applyBranding(document.documentElement, config.branding);
     if (config.title) document.title = config.title;
 
     // Initialize persistence and restore state. Adapter init() may throw
@@ -465,8 +379,8 @@
     // cmi5 §8: an LMS-supplied masteryScore is the authoritative pass
     // threshold for this launch and overrides the manifest. Mutate the
     // imported config object once before any UI reads it so every
-    // downstream consumer (recalculateSuccess, navigation gating, Quiz
-    // page context) sees the same effective value.
+    // downstream consumer (the derived completion/success status, navigation
+    // gating, Quiz page context) sees the same effective value.
     const lmsMastery = adapter.getMasteryScore?.();
     if (typeof lmsMastery === 'number') {
       config.scoring.passingScore = lmsMastery * 100;

package/src/runtime/Sidebar.svelte

@@ -56,7 +56,9 @@
 
       {#if !collapsedSections.has(section.slug)}
         {#each section.lessons as lesson (lesson.slug)}
-          <div class="tessera-nav-lesson-title">{lesson.title}</div>
+          {#if lesson.title}
+            <div class="tessera-nav-lesson-title">{lesson.title}</div>
+          {/if}
           {#each lesson.pages as page (page.index)}
             {@const locked = nav.isPageLocked(page.index)}
             <button

package/src/runtime/adapters/cmi5.ts

@@ -5,7 +5,7 @@ import {
   formatCorrectPattern,
   XAPI_INTERACTION_FORMAT,
 } from '../interaction-format.js';
-import { formatISO8601Duration } from './format.js';
+import { formatISO8601Duration, parseScaled01 } from './format.js';
 import { XAPIPublisher } from '../xapi/publisher.js';
 import { X_API_VERSION } from '../xapi/version.js';
 import type { XAPIAgent } from '../xapi/types.js';
@@ -151,8 +151,8 @@ export class CMI5Adapter implements PersistenceAdapter {
 
     const rawMastery = params.get('masteryScore');
     if (rawMastery !== null && rawMastery !== '') {
-      const m = Number(rawMastery);
-      if (Number.isFinite(m) && m >= 0 && m <= 1) {
+      const m = parseScaled01(rawMastery);
+      if (m !== null) {
         this.#masteryScore = m;
       } else {
         console.warn(
@@ -272,13 +272,9 @@ export class CMI5Adapter implements PersistenceAdapter {
       ) {
         this.#returnURL = this.#launchData.returnURL;
       }
-      if (
-        typeof this.#launchData.masteryScore === 'number' &&
-        Number.isFinite(this.#launchData.masteryScore) &&
-        this.#launchData.masteryScore >= 0 &&
-        this.#launchData.masteryScore <= 1
-      ) {
-        this.#masteryScore = this.#launchData.masteryScore;
+      const launchMastery = parseScaled01(this.#launchData.masteryScore);
+      if (launchMastery !== null) {
+        this.#masteryScore = launchMastery;
       }
     }
 

package/src/runtime/adapters/format.ts

@@ -65,3 +65,9 @@ export function formatISO8601Duration(totalSeconds: number): string {
   if (seconds > 0 || result === 'PT') result += `${seconds}S`;
   return result;
 }
+
+export function parseScaled01(raw: unknown): number | null {
+  if (raw === null || raw === undefined || raw === '') return null;
+  const n = typeof raw === 'number' ? raw : Number(raw);
+  return Number.isFinite(n) && n >= 0 && n <= 1 ? n : null;
+}

package/src/runtime/adapters/retry.ts

@@ -42,7 +42,7 @@ function logRetryGiveUp(
   );
 }
 
-export function formatLMSErrorDetail(
+function formatLMSErrorDetail(
   errorReporter: LMSErrorReporter | undefined,
   code: string,
 ): string {

package/src/runtime/adapters/scorm2004.ts

@@ -5,6 +5,7 @@ import {
   formatISO8601Duration,
   formatISO8601Timestamp,
   formatReal107,
+  parseScaled01,
 } from './format.js';
 
 export interface SCORM2004API {
@@ -92,10 +93,7 @@ export class SCORM2004Adapter extends BaseScormAdapter<SCORM2004API> {
     } catch {
       return null;
     }
-    if (!raw) return null;
-    const n = Number(raw);
-    if (Number.isFinite(n) && n >= 0 && n <= 1) return n;
-    return null;
+    return parseScaled01(raw);
   }
 
   saveState(state: SavedState): void {

package/src/runtime/branding.ts

@@ -0,0 +1,90 @@
+// Two sentinels so the validity check doesn't false-positive when the input
+// normalizes to the initial fillStyle.
+export function parseColor(
+  color: string,
+): { r: number; g: number; b: number } | null {
+  if (
+    typeof CSS !== 'undefined' &&
+    CSS.supports &&
+    !CSS.supports('color', color)
+  ) {
+    return null;
+  }
+  const ctx = document.createElement('canvas').getContext('2d');
+  if (!ctx) return null;
+  ctx.fillStyle = '#000';
+  ctx.fillStyle = color;
+  const onBlack = ctx.fillStyle;
+  ctx.fillStyle = '#fff';
+  ctx.fillStyle = color;
+  const onWhite = ctx.fillStyle;
+  if (onBlack !== onWhite) return null;
+  const hex = String(onBlack).match(
+    /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i,
+  );
+  if (hex)
+    return {
+      r: parseInt(hex[1], 16),
+      g: parseInt(hex[2], 16),
+      b: parseInt(hex[3], 16),
+    };
+  const rgba = String(onBlack).match(
+    /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/,
+  );
+  return rgba ? { r: +rgba[1], g: +rgba[2], b: +rgba[3] } : null;
+}
+
+export function rgbToHsl(
+  r: number,
+  g: number,
+  b: number,
+): { h: number; s: number; l: number } {
+  r /= 255;
+  g /= 255;
+  b /= 255;
+  const max = Math.max(r, g, b),
+    min = Math.min(r, g, b);
+  let h = 0,
+    s = 0;
+  const l = (max + min) / 2;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+    else if (max === g) h = ((b - r) / d + 2) / 6;
+    else h = ((r - g) / d + 4) / 6;
+  }
+  return {
+    h: Math.round(h * 360),
+    s: Math.round(s * 100),
+    l: Math.round(l * 100),
+  };
+}
+
+export function applyBranding(
+  el: HTMLElement,
+  branding: { primaryColor?: string; fontFamily?: string } | undefined,
+): void {
+  if (branding?.primaryColor) {
+    el.style.setProperty('--tessera-primary', branding.primaryColor);
+    const rgb = parseColor(branding.primaryColor);
+    if (rgb) {
+      const hsl = rgbToHsl(rgb.r, rgb.g, rgb.b);
+      el.style.setProperty(
+        '--tessera-primary-light',
+        `hsl(${hsl.h}, ${Math.min(hsl.s + 10, 100)}%, 90%)`,
+      );
+      el.style.setProperty(
+        '--tessera-primary-dark',
+        `hsl(${hsl.h}, ${Math.min(hsl.s + 10, 100)}%, ${Math.max(hsl.l - 15, 10)}%)`,
+      );
+      el.style.setProperty(
+        '--tessera-focus-ring',
+        `0 0 0 3px rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, 0.4)`,
+      );
+    }
+  }
+  if (branding?.fontFamily) {
+    el.style.setProperty('--tessera-font-family', branding.fontFamily);
+  }
+}

package/src/runtime/defaults.ts

@@ -0,0 +1,3 @@
+export const DEFAULT_PASSING_SCORE = 70;
+
+export const DEFAULT_PERCENTAGE_THRESHOLD = 100;

package/src/runtime/hooks.svelte.ts

@@ -122,49 +122,16 @@ export function useQuestion(opts: UseQuestionOptions): UseQuestionHandle {
       reset: opts.reset,
       interaction: () => opts.response(),
     });
-    return {
-      get id() {
-        return q.id;
-      },
-      get submitted() {
-        return q.submitted;
-      },
-      get correct() {
-        return q.correct;
-      },
-      get answer() {
-        return q.answer;
-      },
-      get feedbackVisible() {
-        return q.feedbackVisible;
-      },
-      get locked() {
-        return q.locked;
-      },
-      get isLockedCorrect() {
-        return q.isLockedCorrect;
-      },
-      get render() {
-        return q.render;
-      },
-      setAnswer(a: unknown) {
-        q.setAnswer(a);
-      },
-      commit() {
-        q.commit();
-      },
-      submit() {},
-      reset() {
-        opts.reset?.();
-      },
-      retry() {},
-      canRetry: false,
-      retryCount: 0,
-      mode: 'quiz' as const,
-      setRender(render: unknown) {
-        q.setRender(render);
-      },
-    };
+    const handle = q as UseQuestionHandle;
+    handle.submit = () => {};
+    handle.reset = () => opts.reset?.();
+    handle.retry = () => {};
+    Object.defineProperties(handle, {
+      canRetry: { value: false },
+      retryCount: { value: 0 },
+      mode: { value: 'quiz' },
+    });
+    return handle;
   }
 
   const maxRetries = opts.maxRetries ?? Infinity;
@@ -197,17 +164,14 @@ export function useQuestion(opts: UseQuestionOptions): UseQuestionHandle {
       adapterCtx?.adapter.reportInteraction(opts.id, response, correct);
       committed = true;
     }
-    if (opts.graded && navCtx) {
+    if (navCtx) {
       const pageIndex = navCtx.nav.currentPageIndex;
-      navCtx.progress.markStandaloneQuestion(pageIndex, opts.id, score, true);
-      navCtx.progress.recalculateCompletion(
-        navCtx.manifest.totalPages,
-        navCtx.config,
+      navCtx.progress.markStandaloneQuestion(
+        pageIndex,
+        opts.id,
+        score,
+        !!opts.graded,
       );
-      navCtx.progress.recalculateSuccess(navCtx.config);
-    } else if (navCtx) {
-      const pageIndex = navCtx.nav.currentPageIndex;
-      navCtx.progress.markStandaloneQuestion(pageIndex, opts.id, score, false);
     }
 
     submitted = true;
@@ -357,7 +321,6 @@ export function useCompletion(): {
         return;
       }
       progress.markCompleteManually();
-      progress.recalculateSuccess(config);
     },
     get completionStatus() {
       return progress.completionStatus;

package/src/runtime/interaction-format.ts

@@ -41,14 +41,9 @@ export const SCORM2004_INTERACTION_FORMAT: InteractionFormat = {
   identifier: (v) => v,
 };
 
-export const XAPI_INTERACTION_FORMAT: InteractionFormat = {
-  itemDelim: '[,]',
-  pairDelim: '[.]',
-  rangeDelim: '[:]',
-  supportsNumericRange: true,
-  formatBoolean: (v) => (v ? 'true' : 'false'),
-  identifier: (v) => v,
-};
+// xAPI reuses SCORM 2004's delimiters, numeric-range support, and identity
+// identifier verbatim, so it's the same format object.
+export const XAPI_INTERACTION_FORMAT = SCORM2004_INTERACTION_FORMAT;
 
 /**
  * SCORM `short_identifier_type` / `CMIIdentifier`: alphanumerics +

package/src/runtime/progress.svelte.ts

@@ -1,11 +1,20 @@
 import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 import type { CourseConfig } from './types.js';
+import { DEFAULT_PERCENTAGE_THRESHOLD } from './defaults.js';
 
 export class ProgressState {
   #quizGradedIndices: ReadonlySet<number>;
+  #config: CourseConfig;
+  #totalPages: number;
 
-  constructor(quizGradedIndices: ReadonlySet<number>) {
+  constructor(
+    quizGradedIndices: ReadonlySet<number>,
+    config: CourseConfig,
+    totalPages: number,
+  ) {
     this.#quizGradedIndices = quizGradedIndices;
+    this.#config = config;
+    this.#totalPages = totalPages;
   }
 
   visitedPages = $state(new SvelteSet<number>());
@@ -28,12 +37,16 @@ export class ProgressState {
    * Pages in this set contribute to course success status via their standalone average.
    */
   gradedStandalonePages = $state(new SvelteSet<number>());
-  completionStatus = $state<'incomplete' | 'complete'>('incomplete');
-  successStatus = $state<'unknown' | 'passed' | 'failed'>('unknown');
 
-  // Latch for manual completion. Monotonic; recalc methods bail when set.
+  // Latch for manual completion. Monotonic; only flips forward.
   #manuallyCompleted = $state(false);
 
+  /**
+   * Monotonic counter incremented on every persistable state mutation. App.svelte
+   * subscribes to this single signal to schedule a coalesced save.
+   */
+  version = $state(0);
+
   get manuallyCompleted(): boolean {
     return this.#manuallyCompleted;
   }
@@ -42,41 +55,21 @@ export class ProgressState {
   markCompleteManually(): void {
     if (this.#manuallyCompleted) return;
     this.#manuallyCompleted = true;
-    this.completionStatus = 'complete';
     this.version++;
   }
 
-  /**
-   * Monotonic counter incremented on every persistable state mutation
-   * (visited/scores/chunks/standalone). Callers that need to react to *any*
-   * progress change can subscribe to this single signal instead of iterating
-   * each Map/Set themselves.
-   */
-  version = $state(0);
-
-  /**
-   * Mark a page as visited. Callers must call recalculateCompletion()
-   * afterward to update completionStatus.
-   */
   markVisited(pageIndex: number) {
     if (this.visitedPages.has(pageIndex)) return;
     this.visitedPages.add(pageIndex);
     this.version++;
   }
 
-  /**
-   * Record a quiz score. Callers must call recalculateCompletion()
-   * and recalculateSuccess() afterward to update status fields.
-   */
   quizCompleted(pageIndex: number, score: number) {
     this.quizScores.set(pageIndex, score);
     this.version++;
   }
 
-  /**
-   * Record the highest chunk index revealed on a page. Idempotent — only
-   * advances forward, never backward.
-   */
+  /** Record the highest chunk index revealed on a page. Only advances forward. */
   markChunk(pageIndex: number, chunkIndex: number) {
     const current = this.chunkProgress.get(pageIndex) ?? -1;
     if (chunkIndex <= current) return;
@@ -89,11 +82,6 @@ export class ProgressState {
     return this.chunkProgress.get(pageIndex) ?? -1;
   }
 
-  /**
-   * Record the score for a single standalone question (one created via
-   * `useQuestion` outside a `<Quiz>`). When `graded`, the page is added to
-   * `gradedStandalonePages` so it contributes to course success.
-   */
   markStandaloneQuestion(
     pageIndex: number,
     questionId: string,
@@ -121,66 +109,48 @@ export class ProgressState {
     return sum / pageMap.size;
   }
 
-  recalculateCompletion(totalPages: number, config: CourseConfig) {
-    if (this.#manuallyCompleted) return;
-    if (config.completion.mode === 'manual') return;
-    if (config.completion.mode === 'percentage') {
-      const threshold = config.completion.percentageThreshold ?? 100;
+  completionStatus = $derived.by<'incomplete' | 'complete'>(() => {
+    if (this.#manuallyCompleted) return 'complete';
+    const mode = this.#config.completion.mode;
+    if (mode === 'manual') return 'incomplete';
+    if (mode === 'percentage') {
+      const threshold =
+        this.#config.completion.percentageThreshold ??
+        DEFAULT_PERCENTAGE_THRESHOLD;
       const percent =
-        totalPages > 0 ? (this.visitedPages.size / totalPages) * 100 : 0;
-      this.completionStatus = percent >= threshold ? 'complete' : 'incomplete';
-    } else if (config.completion.mode === 'quiz') {
-      const { indices } = this.#gradedPages();
-      if (indices.length === 0) {
-        this.completionStatus = 'incomplete';
-        return;
-      }
-      const average = this.#gradedAverage(indices);
-      this.completionStatus =
-        average >= config.scoring.passingScore ? 'complete' : 'incomplete';
+        this.#totalPages > 0
+          ? (this.visitedPages.size / this.#totalPages) * 100
+          : 0;
+      return percent >= threshold ? 'complete' : 'incomplete';
     }
-  }
-
-  recalculateSuccess(config: CourseConfig) {
-    if (config.completion.mode === 'manual') {
-      const want = config.completion.requireSuccessStatus;
-      // Stay 'unknown' until manual mark fires, so a learner who never
-      // finishes isn't reported as passed.
-      this.successStatus =
-        this.#manuallyCompleted && want !== undefined ? want : 'unknown';
-      return;
+    const { indices } = this.#gradedPages();
+    if (indices.length === 0) return 'incomplete';
+    return this.#gradedAverage(indices) >= this.#config.scoring.passingScore
+      ? 'complete'
+      : 'incomplete';
+  });
+
+  successStatus = $derived.by<'unknown' | 'passed' | 'failed'>(() => {
+    if (this.#config.completion.mode === 'manual') {
+      const want = this.#config.completion.requireSuccessStatus;
+      return this.#manuallyCompleted && want !== undefined ? want : 'unknown';
     }
-
     const { indices, attempted } = this.#gradedPages();
-
-    if (indices.length === 0) {
-      this.successStatus = 'unknown';
-      return;
-    }
-    // Stay unknown until at least one graded score has been recorded
-    if (!attempted) {
-      this.successStatus = 'unknown';
-      return;
-    }
-    const average = this.#gradedAverage(indices);
-    this.successStatus =
-      average >= config.scoring.passingScore ? 'passed' : 'failed';
-  }
+    if (indices.length === 0 || !attempted) return 'unknown';
+    return this.#gradedAverage(indices) >= this.#config.scoring.passingScore
+      ? 'passed'
+      : 'failed';
+  });
 
   /**
    * Effective graded score for LMS reporting — same union and averaging as
-   * recalculateSuccess, so score and success status can't disagree.
+   * successStatus, so score and success status can't disagree.
    */
   gradedScore(): { average: number; attempted: boolean } {
     const { indices, attempted } = this.#gradedPages();
     return { average: this.#gradedAverage(indices), attempted };
   }
 
-  /**
-   * Union of pages that contribute to graded scoring: pageConfig graded quizzes
-   * plus pages with at least one graded standalone question (deduped).
-   * `attempted` is true if any of those pages has a recorded score.
-   */
   #gradedPages(): { indices: number[]; attempted: boolean } {
     const merged = new Set(this.#quizGradedIndices);
     for (const i of this.gradedStandalonePages) merged.add(i);
@@ -189,18 +159,12 @@ export class ProgressState {
     return { indices, attempted };
   }
 
-  /** Whether a page has any recorded graded score (quiz or standalone). */
   #hasScore(pageIndex: number): boolean {
     if (this.quizScores.has(pageIndex)) return true;
     const pageMap = this.standaloneQuestionScores.get(pageIndex);
     return !!pageMap && pageMap.size > 0;
   }
 
-  /**
-   * Average across the given page indices. Each page contributes its quiz score
-   * if present, otherwise its standalone average. Pages with no recorded score
-   * contribute 0 (matching the existing "unattempted graded quiz = 0" rule).
-   */
   #gradedAverage(indices: number[]): number {
     if (indices.length === 0) return 0;
     let sum = 0;