tessera-learn 0.0.11 → 0.0.13

package/src/runtime/hooks.svelte.ts

@@ -1,5 +1,4 @@
 import { getContext, setContext, onDestroy, onMount, tick } from 'svelte';
-import { SvelteSet } from 'svelte/reactivity';
 import type { Interaction } from './interaction.js';
 import { isCorrect as isCorrectInteraction } from './interaction.js';
 import {
@@ -9,11 +8,7 @@ import {
   getPageContext,
   requireUserStateStore,
 } from './contexts.js';
-import {
-  resolveFeedbackMode,
-  resolveRetryStrategy,
-  type QuizQuestionResult,
-} from './quiz-policy.js';
+import { QuizEngine } from './quiz-engine.svelte.js';
 
 /**
  * Per-question handle exposed to both the quiz shell (via `useQuiz().questions`)
@@ -100,7 +95,7 @@ export interface UseQuestionHandle extends Question {
 
 const TESSERA_QUIZ = 'tessera-quiz' as const;
 
-interface QuestionInternal extends Question {
+export interface QuestionInternal extends Question {
   setRender(render: unknown): void;
 }
 
@@ -128,23 +123,47 @@ export function useQuestion(opts: UseQuestionOptions): UseQuestionHandle {
       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(); },
+      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?.(); },
+      reset() {
+        opts.reset?.();
+      },
       retry() {},
       canRetry: false,
       retryCount: 0,
       mode: 'quiz' as const,
-      setRender(render: unknown) { q.setRender(render); },
+      setRender(render: unknown) {
+        q.setRender(render);
+      },
     };
   }
 
@@ -163,7 +182,7 @@ export function useQuestion(opts: UseQuestionOptions): UseQuestionHandle {
     adapterCtx?.adapter.reportInteraction(
       opts.id,
       response,
-      isCorrectInteraction(response)
+      isCorrectInteraction(response),
     );
   }
 
@@ -172,11 +191,7 @@ export function useQuestion(opts: UseQuestionOptions): UseQuestionHandle {
     const response = opts.response();
     currentAnswer = response.response;
     correct = isCorrectInteraction(response);
-    const score = opts.score
-      ? opts.score()
-      : correct === true
-        ? 100
-        : 0;
+    const score = opts.score ? opts.score() : correct === true ? 100 : 0;
 
     if (!committed) {
       adapterCtx?.adapter.reportInteraction(opts.id, response, correct);
@@ -185,7 +200,10 @@ export function useQuestion(opts: UseQuestionOptions): UseQuestionHandle {
     if (opts.graded && navCtx) {
       const pageIndex = navCtx.nav.currentPageIndex;
       navCtx.progress.markStandaloneQuestion(pageIndex, opts.id, score, true);
-      navCtx.progress.recalculateCompletion(navCtx.manifest.totalPages, navCtx.config);
+      navCtx.progress.recalculateCompletion(
+        navCtx.manifest.totalPages,
+        navCtx.config,
+      );
       navCtx.progress.recalculateSuccess(navCtx.config);
     } else if (navCtx) {
       const pageIndex = navCtx.nav.currentPageIndex;
@@ -210,21 +228,41 @@ export function useQuestion(opts: UseQuestionOptions): UseQuestionHandle {
   }
 
   return {
-    get id() { return opts.id; },
-    get submitted() { return submitted; },
-    get correct() { return correct; },
-    get answer() { return currentAnswer; },
-    get feedbackVisible() { return submitted; },
-    get locked() { return submitted; },
-    get isLockedCorrect() { return submitted && correct === true && retryCount >= maxRetries; },
+    get id() {
+      return opts.id;
+    },
+    get submitted() {
+      return submitted;
+    },
+    get correct() {
+      return correct;
+    },
+    get answer() {
+      return currentAnswer;
+    },
+    get feedbackVisible() {
+      return submitted;
+    },
+    get locked() {
+      return submitted;
+    },
+    get isLockedCorrect() {
+      return submitted && correct === true && retryCount >= maxRetries;
+    },
     render: undefined,
-    setAnswer(a: unknown) { currentAnswer = a; },
+    setAnswer(a: unknown) {
+      currentAnswer = a;
+    },
     commit,
     submit,
     reset,
     retry,
-    get canRetry() { return retryCount < maxRetries; },
-    get retryCount() { return retryCount; },
+    get canRetry() {
+      return retryCount < maxRetries;
+    },
+    get retryCount() {
+      return retryCount;
+    },
     mode: 'standalone' as const,
     setRender() {},
   };
@@ -233,18 +271,34 @@ export function useQuestion(opts: UseQuestionOptions): UseQuestionHandle {
 export function useNavigation() {
   const { nav, manifest } = requireNavContext('useNavigation()');
   return {
-    get currentPage() { return manifest.pages[nav.currentPageIndex]; },
-    get currentPageIndex() { return nav.currentPageIndex; },
-    get pages() { return manifest.pages; },
+    get currentPage() {
+      return manifest.pages[nav.currentPageIndex];
+    },
+    get currentPageIndex() {
+      return nav.currentPageIndex;
+    },
+    get pages() {
+      return manifest.pages;
+    },
     goTo(slug: string) {
       const index = manifest.pages.findIndex((p) => p.slug === slug);
       if (index >= 0) nav.goToPage(index);
     },
-    goToIndex(index: number) { nav.goToPage(index); },
-    next() { nav.goNext(); },
-    prev() { nav.goPrev(); },
-    get canGoNext() { return nav.canGoNext; },
-    get canGoPrev() { return nav.canGoPrev; },
+    goToIndex(index: number) {
+      nav.goToPage(index);
+    },
+    next() {
+      nav.goNext();
+    },
+    prev() {
+      nav.goPrev();
+    },
+    get canGoNext() {
+      return nav.canGoNext;
+    },
+    get canGoPrev() {
+      return nav.canGoPrev;
+    },
     canAccess(slug: string) {
       const index = manifest.pages.findIndex((p) => p.slug === slug);
       return index >= 0 && !nav.isPageLocked(index);
@@ -255,12 +309,24 @@ export function useNavigation() {
 export function useProgress() {
   const { progress } = requireNavContext('useProgress()');
   return {
-    get visitedPages() { return progress.visitedPages; },
-    get quizScores() { return progress.quizScores; },
-    get chunkProgress() { return progress.chunkProgress; },
-    get completionStatus() { return progress.completionStatus; },
-    get successStatus() { return progress.successStatus; },
-    markVisited(pageIndex: number) { progress.markVisited(pageIndex); },
+    get visitedPages() {
+      return progress.visitedPages;
+    },
+    get quizScores() {
+      return progress.quizScores;
+    },
+    get chunkProgress() {
+      return progress.chunkProgress;
+    },
+    get completionStatus() {
+      return progress.completionStatus;
+    },
+    get successStatus() {
+      return progress.successStatus;
+    },
+    markVisited(pageIndex: number) {
+      progress.markVisited(pageIndex);
+    },
     markChunk(pageIndex: number, chunkIndex: number) {
       progress.markChunk(pageIndex, chunkIndex);
     },
@@ -277,7 +343,7 @@ export function useCompletion(): {
   markComplete(): void;
   readonly completionStatus: 'incomplete' | 'complete';
 } {
-  const { progress, manifest, config } = requireNavContext('useCompletion()');
+  const { progress, config } = requireNavContext('useCompletion()');
   return {
     markComplete() {
       if (config.completion.mode !== 'manual') {
@@ -285,7 +351,7 @@ export function useCompletion(): {
           warnedNonManualCompletion = true;
           console.warn(
             "Tessera: useCompletion().markComplete() ignored — completion.mode is not 'manual'. " +
-              '(This warning is shown once per session.)'
+              '(This warning is shown once per session.)',
           );
         }
         return;
@@ -299,14 +365,20 @@ export function useCompletion(): {
   };
 }
 
-export function usePersistence<T = unknown>(key: string): {
+export function usePersistence<T = unknown>(
+  key: string,
+): {
   get(): T | null;
   set(value: T): void;
 } {
   const store = requireUserStateStore('usePersistence()');
   return {
-    get(): T | null { return (store.get(key) as T | null) ?? null; },
-    set(value: T) { store.set(key, value); },
+    get(): T | null {
+      return (store.get(key) as T | null) ?? null;
+    },
+    set(value: T) {
+      store.set(key, value);
+    },
   };
 }
 
@@ -358,15 +430,6 @@ export interface UseQuizInternalHandle extends UseQuizHandle {
   isLockedCorrect(index: number): boolean;
 }
 
-interface InternalQuestion {
-  id: string;
-  weight: number;
-  checkAnswer: (answer?: unknown) => boolean;
-  reset?: () => void;
-  interaction?: () => Interaction;
-  render: unknown;
-}
-
 export function __warnUnsubmittedQuiz(stats: {
   questionsCount: number;
   answersCount: number;
@@ -377,7 +440,7 @@ export function __warnUnsubmittedQuiz(stats: {
   console.warn(
     '[tessera] useQuiz: submit() was never called before unmount, but the learner answered ' +
       `${stats.answersCount} of ${stats.questionsCount} questions. ` +
-      'Did your custom quiz shell forget to call handle.submit()?'
+      'Did your custom quiz shell forget to call handle.submit()?',
   );
 }
 
@@ -385,19 +448,20 @@ export function __warnEmptyQuiz(questionsCount: number): void {
   if (questionsCount > 0) return;
   console.warn(
     '[tessera] useQuiz: quiz mounted with no registered questions. Question widgets ' +
-      'must call useQuestion() to be scored and reported to the LMS.'
+      'must call useQuestion() to be scored and reported to the LMS.',
   );
 }
 
-export function useQuiz(opts: { element: () => HTMLElement | null }): UseQuizHandle {
+export function useQuiz(opts: {
+  element: () => HTMLElement | null;
+}): UseQuizHandle {
   const pageCtx = getPageContext();
   const adapterCtx = getAdapterContext();
   if (!pageCtx?.quiz) {
     throw new Error(
-      'useQuiz() must be called on a page with a quiz config (export const pageConfig = { quiz: { ... } }).'
+      'useQuiz() must be called on a page with a quiz config (export const pageConfig = { quiz: { ... } }).',
     );
   }
-  const quizConfig = pageCtx.quiz;
 
   // A second useQuiz on the same page silently overwrites the first quiz's
   // pageIndex-keyed score; warn but don't prevent (some pages compose hosts).
@@ -405,273 +469,35 @@ export function useQuiz(opts: { element: () => HTMLElement | null }): UseQuizHan
   if (existing) {
     console.warn(
       '[tessera] useQuiz: a second quiz registered on this page; ' +
-        'quiz scores are keyed by pageIndex and the later submit will overwrite the earlier one.'
-    );
-  }
-
-  const maxAttempts = quizConfig.maxAttempts ?? Infinity;
-  const feedbackPredicate = resolveFeedbackMode(quizConfig);
-  const retryPredicate = resolveRetryStrategy(quizConfig);
-
-  let internalQuestions = $state<InternalQuestion[]>([]);
-  const answers = new Map<number, unknown>();
-  const reportedAnswers = new Map<number, string>();
-  let answersVersion = $state(0);
-  let submitted = $state(false);
-  let reviewing = $state(false);
-  let score = $state(0);
-  let attemptCount = $state(0);
-  const feedbackShown = new SvelteSet<number>();
-  const lockedCorrect = new SvelteSet<number>();
-  let submitCalled = false;
-
-  const seenIds = new Set<string>();
-
-  const totalQuestions = $derived(internalQuestions.length);
-  const allAnswered = $derived(
-    (void answersVersion, totalQuestions > 0 && answers.size >= totalQuestions)
-  );
-  const canSubmit = $derived(!submitted && allAnswered);
-  const canRetry = $derived(submitted && attemptCount < maxAttempts);
-  const state: 'answering' | 'submitted' | 'reviewing' = $derived(
-    reviewing ? 'reviewing' : submitted ? 'submitted' : 'answering'
-  );
-
-  function dispatch(name: string, detail?: unknown): void {
-    const el = opts.element();
-    if (!el) return;
-    el.dispatchEvent(new CustomEvent(name, { detail, bubbles: true }));
-  }
-
-  function setAnswerInternal(index: number, answer: unknown): void {
-    answers.set(index, answer);
-    answersVersion++;
-    dispatch('tessera-quiz-question-answered', { index });
-  }
-
-  function commitInternal(index: number): void {
-    if (!adapterCtx) return;
-    const q = internalQuestions[index];
-    if (!q || typeof q.interaction !== 'function') return;
-    const interaction = q.interaction();
-    if (!interaction) return;
-    const fingerprint = JSON.stringify(interaction);
-    if (reportedAnswers.get(index) === fingerprint) return;
-    const answer = answers.has(index) ? answers.get(index) : undefined;
-    adapterCtx.adapter.reportInteraction(q.id, interaction, q.checkAnswer(answer));
-    reportedAnswers.set(index, fingerprint);
-  }
-
-  function getAnswerInternal(index: number): unknown {
-    void answersVersion;
-    return answers.get(index);
-  }
-
-  function setRenderInternal(index: number, render: unknown): void {
-    if (internalQuestions[index]) internalQuestions[index].render = render;
-  }
-
-  function getRenderInternal(index: number): unknown {
-    return internalQuestions[index]?.render;
-  }
-
-  function feedbackVisibleInternal(index: number): boolean {
-    if (quizConfig.feedbackMode === 'never') return false;
-    return feedbackPredicate({
-      questionIndex: index,
-      submitted,
-      reviewing,
-      hasAnswered: answers.has(index),
-      revealed: feedbackShown.has(index),
-      attemptCount,
-    });
-  }
-
-  function revealFeedbackInternal(index: number): void {
-    if (quizConfig.feedbackMode === 'never') return;
-    feedbackShown.add(index);
-  }
-
-  function isLockedCorrectInternal(index: number): boolean {
-    return lockedCorrect.has(index);
-  }
-
-  function makeQuestionHandle(i: number): QuestionInternal {
-    return {
-      get id() { return internalQuestions[i].id; },
-      get submitted() { return submitted; },
-      get correct() {
-        if (!submitted) return null;
-        const a = answers.has(i) ? answers.get(i) : undefined;
-        return internalQuestions[i].checkAnswer(a);
-      },
-      get answer() { return getAnswerInternal(i); },
-      get feedbackVisible() { return feedbackVisibleInternal(i); },
-      get locked() {
-        return submitted || feedbackVisibleInternal(i) || isLockedCorrectInternal(i);
-      },
-      get isLockedCorrect() { return isLockedCorrectInternal(i); },
-      get render() { return getRenderInternal(i); },
-      setAnswer(a: unknown) { setAnswerInternal(i, a); },
-      commit() { commitInternal(i); },
-      setRender(r: unknown) { setRenderInternal(i, r); },
-    };
-  }
-
-  let questionHandles = $state<QuestionInternal[]>([]);
-
-  function registerQuestion(api: UseQuizQuestionApi): QuestionInternal {
-    if (seenIds.has(api.id)) {
-      console.warn(
-        `[tessera] useQuiz: duplicate question id "${api.id}" — ` +
-          'each question id must be unique within a quiz (LMS interaction records key by id).'
-      );
-    }
-    seenIds.add(api.id);
-    const internal: InternalQuestion = {
-      id: api.id,
-      weight: typeof api.weight === 'number' && api.weight > 0 ? api.weight : 1,
-      checkAnswer: api.checkAnswer,
-      reset: api.reset,
-      interaction: api.interaction,
-      render: undefined,
-    };
-    internalQuestions.push(internal);
-    const handle = makeQuestionHandle(internalQuestions.length - 1);
-    questionHandles.push(handle);
-    return handle;
-  }
-
-  function computeScore(): { rounded: number; correctCount: number } {
-    let weighted = 0;
-    let totalWeight = 0;
-    let correctCount = 0;
-    for (let i = 0; i < internalQuestions.length; i++) {
-      const q = internalQuestions[i];
-      const a = answers.has(i) ? answers.get(i) : undefined;
-      const ok = q.checkAnswer(a);
-      totalWeight += q.weight;
-      if (ok) {
-        weighted += q.weight;
-        correctCount++;
-      }
-    }
-    if (totalWeight === 0) return { rounded: 0, correctCount: 0 };
-    return { rounded: Math.round((weighted / totalWeight) * 100), correctCount };
-  }
-
-  function submit(): void {
-    submitCalled = true;
-    if (submitted) return;
-    if (!allAnswered) return;
-    const el = opts.element();
-    if (!el) {
-      console.warn(
-        '[tessera] useQuiz: submit() ran but the host element was null — no LMS bridge ' +
-          'listener exists, so this score will not be persisted. Make sure your custom ' +
-          'quiz shell binds the element it passes to useQuiz({ element: () => ... }).'
-      );
-      return;
-    }
-    el.dispatchEvent(new CustomEvent('tessera-quiz-before-submit', { bubbles: true }));
-
-    for (let i = 0; i < internalQuestions.length; i++) commitInternal(i);
-
-    const { rounded } = computeScore();
-    score = rounded;
-    submitted = true;
-    attemptCount++;
-
-    el.dispatchEvent(
-      new CustomEvent('tessera-quiz-complete', {
-        detail: { score: rounded },
-        bubbles: true,
-      })
+        'quiz scores are keyed by pageIndex and the later submit will overwrite the earlier one.',
     );
   }
 
-  function startReview(): void {
-    if (!submitted) return;
-    reviewing = true;
-  }
-
-  function exitReview(): void {
-    reviewing = false;
-  }
-
-  function retry(): void {
-    if (!canRetry) return;
-    const results: QuizQuestionResult[] = [];
-    for (let i = 0; i < internalQuestions.length; i++) {
-      const a = answers.has(i) ? answers.get(i) : undefined;
-      results.push({
-        interaction: internalQuestions[i].interaction?.() ?? ({} as never),
-        correct: internalQuestions[i].checkAnswer(a),
-        weight: internalQuestions[i].weight,
-      });
-    }
-    const newLocked = retryPredicate(results);
-    const preserved = new Map<number, unknown>();
-    for (const i of newLocked) {
-      if (answers.has(i)) preserved.set(i, answers.get(i));
-    }
-    lockedCorrect.clear();
-    for (const i of newLocked) lockedCorrect.add(i);
-    answers.clear();
-    reportedAnswers.clear();
-    for (const [i, a] of preserved) answers.set(i, a);
-    for (let i = 0; i < internalQuestions.length; i++) {
-      if (!newLocked.has(i) && internalQuestions[i].reset) internalQuestions[i].reset!();
-    }
-    answersVersion++;
-    feedbackShown.clear();
-    submitted = false;
-    reviewing = false;
-    score = 0;
-    dispatch('tessera-quiz-retry');
-  }
-
-  function revealFeedback(q: Question): void {
-    const index = internalQuestions.findIndex((iq) => iq.id === q.id);
-    if (index >= 0) revealFeedbackInternal(index);
-  }
+  const engine = new QuizEngine({
+    quizConfig: pageCtx.quiz,
+    passingScore: () => pageCtx.passingScore,
+    report: (id, interaction, correct) =>
+      adapterCtx?.adapter.reportInteraction(id, interaction, correct),
+    dispatch: (name, detail) => {
+      const el = opts.element();
+      if (!el) return false;
+      el.dispatchEvent(new CustomEvent(name, { detail, bubbles: true }));
+      return true;
+    },
+  });
 
-  setContext<QuizContextValue>(TESSERA_QUIZ, { registerQuestion });
+  setContext<QuizContextValue>(TESSERA_QUIZ, {
+    registerQuestion: (api) => engine.registerQuestion(api),
+  });
 
   onMount(() => {
     if (!import.meta.env?.DEV) return;
-    void tick().then(() => __warnEmptyQuiz(internalQuestions.length));
+    void tick().then(() => __warnEmptyQuiz(engine.questions.length));
   });
 
   onDestroy(() => {
-    __warnUnsubmittedQuiz({
-      questionsCount: internalQuestions.length,
-      answersCount: answers.size,
-      submitCalled,
-    });
+    __warnUnsubmittedQuiz(engine.stats);
   });
 
-  const handle: UseQuizInternalHandle = {
-    get state() { return state; },
-    get questions() { return questionHandles; },
-    get canSubmit() { return canSubmit; },
-    get canRetry() { return canRetry; },
-    get score() { return score; },
-    get passingScore() { return pageCtx.passingScore; },
-    get attemptCount() { return attemptCount; },
-    submit,
-    startReview,
-    exitReview,
-    retry,
-    revealFeedback,
-    registerQuestion,
-    setAnswer: setAnswerInternal,
-    getAnswer: getAnswerInternal,
-    setRender: setRenderInternal,
-    getRender: getRenderInternal,
-    feedbackVisible: feedbackVisibleInternal,
-    revealFeedbackByIndex: revealFeedbackInternal,
-    isLockedCorrect: isLockedCorrectInternal,
-  };
-  return handle;
+  return engine;
 }