tessera-learn 0.0.1 → 0.0.2

package/src/runtime/adapters/scorm2004.ts

@@ -1,7 +1,5 @@
-import type { PersistenceAdapter, SavedState } from '../persistence.js';
-import type { Interaction } from '../interaction.js';
-import { buildScormInteractionFields } from '../interaction-format.js';
-import { WriteQueue, callSync, withRetry, formatISO8601Duration } from './retry.js';
+import { BaseScormAdapter, type ScormDialect } from './scorm-base.js';
+import { formatISO8601Duration } from './retry.js';
 
 /**
  * SCORM 2004 API interface.
@@ -17,6 +15,26 @@ export interface SCORM2004API {
   GetDiagnostic(errorCode: string): string;
 }
 
+const SCORM2004_DIALECT: ScormDialect<SCORM2004API> = {
+  sessionTimeKey: 'cmi.session_time',
+  formatDuration: formatISO8601Duration,
+  interactionFields: {
+    responseField: 'learner_response',
+    timestampField: 'timestamp',
+    timestamp: () => new Date().toISOString(),
+    // SCORM 2004 accepts the canonical interaction `type` strings unchanged.
+    typeValue: (t) => t,
+    resultLabels: { correct: 'correct', incorrect: 'incorrect' },
+  },
+  initialize: (api) => api.Initialize(''),
+  terminate: (api) => api.Terminate(''),
+  getValue: (api, key) => api.GetValue(key),
+  setValue: (api, key, value) => api.SetValue(key, value),
+  commit: (api) => api.Commit(''),
+  getLastError: (api) => api.GetLastError(),
+  getErrorString: (api, code) => api.GetErrorString(code),
+};
+
 /**
  * SCORM 2004 persistence adapter.
  *
@@ -24,70 +42,19 @@ export interface SCORM2004API {
  * On terminate, the queue is drained synchronously (single attempt)
  * since async retries cannot complete during page unload.
  */
-export class SCORM2004Adapter implements PersistenceAdapter {
-  #api: SCORM2004API;
-  #queue = new WriteQueue();
-  #state: SavedState | null = null;
-  #terminated = false;
-  #interactionCount = 0;
-
+export class SCORM2004Adapter extends BaseScormAdapter<SCORM2004API> {
   constructor(api: SCORM2004API) {
-    this.#api = api;
-    // Wire up GetLastError/GetErrorString so retry warnings can name the
-    // real LMS failure (e.g. "405 Incorrect Data Type") instead of a
-    // generic "LMS call failed" — production triage needs the code.
-    this.#queue.errorReporter = {
-      code: () => this.#api.GetLastError(),
-      message: (c) => this.#api.GetErrorString(c),
-    };
-  }
-
-  /** Expose the underlying SCORM 2004 API so xAPI actor synthesis can read learner fields. */
-  getAPI(): SCORM2004API {
-    return this.#api;
-  }
-
-  async init(): Promise<void> {
-    await withRetry(() => this.#api.Initialize(''));
-
-    try {
-      const raw = this.#api.GetValue('cmi.suspend_data');
-      if (raw && raw.trim()) {
-        this.#state = JSON.parse(raw);
-      }
-    } catch {
-      this.#state = null;
-    }
-
-    // Continue cmi.interactions.n indexing where the previous session left
-    // off. Restarting at 0 would overwrite prior records.
-    try {
-      const count = this.#api.GetValue('cmi.interactions._count');
-      const n = parseInt(count, 10);
-      if (Number.isFinite(n) && n >= 0) this.#interactionCount = n;
-    } catch {
-      // Fallback to 0 if _count read fails.
-    }
-  }
-
-  getState(): SavedState | null {
-    return this.#state;
-  }
-
-  saveState(state: SavedState): void {
-    this.#state = state;
-    const json = JSON.stringify(state);
-    this.#queue.enqueue(() => this.#api.SetValue('cmi.suspend_data', json));
+    super(api, SCORM2004_DIALECT);
   }
 
   setScore(score: number): void {
-    this.#queue.enqueue(() =>
-      this.#api.SetValue('cmi.score.raw', String(score))
+    this.queue.enqueue(() =>
+      this.api.SetValue('cmi.score.raw', String(score))
     );
-    this.#queue.enqueue(() => this.#api.SetValue('cmi.score.min', '0'));
-    this.#queue.enqueue(() => this.#api.SetValue('cmi.score.max', '100'));
-    this.#queue.enqueue(() =>
-      this.#api.SetValue('cmi.score.scaled', String(score / 100))
+    this.queue.enqueue(() => this.api.SetValue('cmi.score.min', '0'));
+    this.queue.enqueue(() => this.api.SetValue('cmi.score.max', '100'));
+    this.queue.enqueue(() =>
+      this.api.SetValue('cmi.score.scaled', String(score / 100))
     );
   }
 
@@ -96,67 +63,19 @@ export class SCORM2004Adapter implements PersistenceAdapter {
   // logic internally via course.config.js settings.
   setCompletionStatus(status: 'incomplete' | 'complete'): void {
     const value = status === 'complete' ? 'completed' : 'incomplete';
-    this.#queue.enqueue(() =>
-      this.#api.SetValue('cmi.completion_status', value)
+    this.queue.enqueue(() =>
+      this.api.SetValue('cmi.completion_status', value)
     );
   }
 
   setSuccessStatus(status: 'passed' | 'failed' | 'unknown'): void {
     // "unknown" is a valid SCORM 2004 value — setting it explicitly prevents
     // LMSes (notably SCORM Cloud) from rolling up a null status to "passed".
-    this.#queue.enqueue(() =>
-      this.#api.SetValue('cmi.success_status', status)
-    );
-  }
-
-  setDuration(seconds: number): void {
-    const formatted = formatISO8601Duration(seconds);
-    this.#queue.enqueue(() =>
-      this.#api.SetValue('cmi.session_time', formatted)
-    );
+    this.queue.enqueue(() => this.api.SetValue('cmi.success_status', status));
   }
 
   setExit(mode: 'suspend' | 'normal'): void {
     // SCORM 2004 §4.2 cmi.exit vocabulary: time-out, suspend, logout, normal, "".
-    this.#queue.enqueue(() => this.#api.SetValue('cmi.exit', mode));
-  }
-
-  reportInteraction(
-    questionId: string,
-    interaction: Interaction,
-    correct: boolean | null
-  ): void {
-    const n = this.#interactionCount++;
-    const fields = buildScormInteractionFields(
-      `cmi.interactions.${n}`,
-      questionId,
-      interaction,
-      correct,
-      {
-        responseField: 'learner_response',
-        timestampField: 'timestamp',
-        timestamp: new Date().toISOString(),
-        typeValue: interaction.type,
-        resultLabels: { correct: 'correct', incorrect: 'incorrect' },
-      }
-    );
-    for (const [key, value] of fields) {
-      this.#queue.enqueue(() => this.#api.SetValue(key, value));
-    }
-  }
-
-  commit(): void {
-    this.#queue.enqueue(() => this.#api.Commit(''));
-  }
-
-  terminate(): void {
-    if (this.#terminated) return;
-    this.#terminated = true;
-    // During page unload, async retries can't run.
-    // Drain any pending queue operations synchronously (single attempt each),
-    // then commit and terminate synchronously.
-    this.#queue.drainSync();
-    callSync(() => this.#api.Commit(''));
-    callSync(() => this.#api.Terminate(''));
+    this.queue.enqueue(() => this.api.SetValue('cmi.exit', mode));
   }
 }

package/src/runtime/hooks.svelte.ts

@@ -10,6 +10,12 @@ import {
 } from './contexts.js';
 import { buildQuizInteractions } from '../components/quiz-payload.js';
 import type { QuizContext } from '../components/quiz-payload.js';
+import {
+  resolveFeedbackMode,
+  resolveRetryStrategy,
+  type QuizPolicyConfig,
+  type QuizQuestionResult,
+} from './quiz-policy.js';
 
 export interface UseQuestionOptions {
   /** Stable identifier used for LMS interaction reporting. Must be unique on the page. */
@@ -22,6 +28,8 @@ export interface UseQuestionOptions {
    * Default 1; ignored in standalone mode.
    */
   weight?: number;
+  /** Standalone retry cap. Default `Infinity`. Ignored inside a `<Quiz>`. */
+  maxRetries?: number;
   /** Called on submit — returns the current learner response payload. */
   response: () => Interaction;
   /**
@@ -38,8 +46,12 @@ export interface UseQuestionOptions {
 export interface UseQuestionHandle {
   submit(): void;
   reset(): void;
+  /** Standalone retry. No-op once `maxRetries` is hit or inside a `<Quiz>`. */
+  retry(): void;
   readonly submitted: boolean;
   readonly correct: boolean | null;
+  readonly canRetry: boolean;
+  readonly retryCount: number;
   readonly mode: 'standalone' | 'quiz';
   /** Index returned by the parent Quiz registration, used for per-question context reads. Undefined in standalone mode. */
   readonly quizIndex: number | undefined;
@@ -68,18 +80,23 @@ export function useQuestion(opts: UseQuestionOptions): UseQuestionHandle {
     return {
       submit() {},
       reset() { opts.reset?.(); },
+      retry() {},
       get submitted() { return quizCtx.submitted ?? false; },
       get correct() {
         if (!(quizCtx.submitted ?? false)) return null;
         return isCorrectInteraction(opts.response());
       },
+      canRetry: false,
+      retryCount: 0,
       mode: 'quiz' as const,
       quizIndex,
     };
   }
 
+  const maxRetries = opts.maxRetries ?? Infinity;
   let submitted = $state(false);
   let correct = $state<boolean | null>(null);
+  let retryCount = $state(0);
 
   function submit() {
     if (submitted) return;
@@ -111,11 +128,20 @@ export function useQuestion(opts: UseQuestionOptions): UseQuestionHandle {
     opts.reset?.();
   }
 
+  function retry() {
+    if (retryCount >= maxRetries) return;
+    retryCount++;
+    reset();
+  }
+
   return {
     submit,
     reset,
+    retry,
     get submitted() { return submitted; },
     get correct() { return correct; },
+    get canRetry() { return retryCount < maxRetries; },
+    get retryCount() { return retryCount; },
     mode: 'standalone' as const,
     quizIndex: undefined,
   };
@@ -267,7 +293,6 @@ export function useQuiz(opts: { element: () => HTMLElement | null }): UseQuizHan
     );
   }
   const quizConfig = pageCtx.quiz;
-  const passingScore = pageCtx.passingScore ?? 70;
 
   // Dev-mode warning: a second useQuiz on the same page silently overwrites
   // the first quiz's pageIndex-keyed score. We can't prevent it (some pages
@@ -283,9 +308,15 @@ export function useQuiz(opts: { element: () => HTMLElement | null }): UseQuizHan
 
   const maxAttempts = quizConfig.maxAttempts ?? Infinity;
   const showFeedback = quizConfig.showFeedback ?? true;
-  const feedbackMode: 'review' | 'immediate' =
-    showFeedback && quizConfig.feedbackMode === 'immediate' ? 'immediate' : 'review';
-  const retryMode: 'full' | 'incorrect-only' = quizConfig.retryMode ?? 'full';
+
+  const policyCfg = quizConfig as QuizPolicyConfig;
+  const feedbackPredicate = resolveFeedbackMode(policyCfg);
+  const retryPredicate = resolveRetryStrategy(policyCfg);
+  // Lock the answer once feedback is revealed in 'immediate' mode and under any
+  // custom predicate (opaque; lock conservatively). 'review' mode is post-submit.
+  const revealsLockAnswer =
+    policyCfg.feedbackMode === 'immediate' ||
+    typeof policyCfg.feedbackMode === 'function';
 
   interface InternalQuestion extends UseQuizQuestionApi {
     weight: number;
@@ -380,9 +411,14 @@ export function useQuiz(opts: { element: () => HTMLElement | null }): UseQuizHan
 
   function feedbackVisible(index: number): boolean {
     if (!showFeedback) return false;
-    if (feedbackMode === 'immediate' && feedbackShown.has(index)) return true;
-    if (submitted && reviewing) return true;
-    return false;
+    return feedbackPredicate({
+      questionIndex: index,
+      submitted,
+      reviewing,
+      hasAnswered: answers.has(index),
+      revealed: feedbackShown.has(index),
+      attemptCount,
+    });
   }
 
   function revealFeedback(index: number): void {
@@ -442,7 +478,6 @@ export function useQuiz(opts: { element: () => HTMLElement | null }): UseQuizHan
     attemptCount++;
 
     const interactions = buildQuizInteractions(questions, answers);
-    void passingScore; // reserved for future custom-shell extensions
     el.dispatchEvent(
       new CustomEvent('tessera-quiz-complete', {
         detail: { score: rounded, interactions },
@@ -462,26 +497,25 @@ export function useQuiz(opts: { element: () => HTMLElement | null }): UseQuizHan
 
   function retry(): void {
     if (!canRetry) return;
-    if (retryMode === 'incorrect-only') {
-      const newLocked = new Set<number>();
-      const preserved = new Map<number, unknown>();
-      for (let i = 0; i < questions.length; i++) {
-        const a = answers.has(i) ? answers.get(i) : undefined;
-        if (questions[i].checkAnswer(a)) {
-          newLocked.add(i);
-          preserved.set(i, a);
-        }
-      }
-      lockedCorrect = newLocked;
-      answers.clear();
-      for (const [i, a] of preserved) answers.set(i, a);
-      for (let i = 0; i < questions.length; i++) {
-        if (!newLocked.has(i) && questions[i].reset) questions[i].reset!();
-      }
-    } else {
-      lockedCorrect = new Set();
-      answers.clear();
-      for (const q of questions) q.reset?.();
+    const results: QuizQuestionResult[] = [];
+    for (let i = 0; i < questions.length; i++) {
+      const a = answers.has(i) ? answers.get(i) : undefined;
+      results.push({
+        interaction: questions[i].interaction?.() ?? ({} as never),
+        correct: questions[i].checkAnswer(a),
+        weight: questions[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 = newLocked;
+    answers.clear();
+    for (const [i, a] of preserved) answers.set(i, a);
+    for (let i = 0; i < questions.length; i++) {
+      if (!newLocked.has(i) && questions[i].reset) questions[i].reset!();
     }
     answersVersion++;
     feedbackShown = new Set();
@@ -507,7 +541,7 @@ export function useQuiz(opts: { element: () => HTMLElement | null }): UseQuizHan
       return (i: number) =>
         submitted ||
         lockedCorrect.has(i) ||
-        (feedbackMode === 'immediate' && feedbackShown.has(i));
+        (revealsLockAnswer && feedbackShown.has(i));
     },
     get isLockedCorrect() { return (i: number) => lockedCorrect.has(i); },
   });

package/src/runtime/xapi/client.ts

@@ -6,8 +6,8 @@ import type {
   Statement,
   DestinationOutcome,
 } from './types.js';
-import { XAPIPublisher, XAPIConfigError } from './publisher.js';
-import { validatePartialStatement } from './validation.js';
+import { XAPIPublisher } from './publisher.js';
+import { validatePartialStatement, XAPIConfigError } from './validation.js';
 import { uuidv4 } from './uuid.js';
 
 /**

package/src/runtime/xapi/publisher.ts

@@ -15,15 +15,12 @@ import {
   XAPIConfigError,
   XAPIStatementError,
 } from './validation.js';
+import { RETRY_ATTEMPTS, backoffMs } from '../adapters/retry.js';
 
 /** cmi5 §9.6.2 — well-known IRI owned by ADL for the cmi5 session id extension. */
 const CMI5_SESSIONID_EXT =
   'https://w3id.org/xapi/cmi5/context/extensions/sessionid';
 
-// Re-exported so existing callers (xapi/client.ts, tests, etc.) that pull
-// these symbols from the publisher entry point keep working.
-export { XAPIConfigError, XAPIStatementError, validateAgent, validateAuthCredential };
-
 /**
  * Combine a field label (e.g. `xapi.actor`) with the prefix-friendly suffix
  * returned by `validateAgent`. Sub-field suffixes start with `.` and chain
@@ -59,6 +56,8 @@ export interface XAPIPublisherOptions {
    * Set by the cmi5 adapter and by 'lms'-inherited destinations under cmi5.
    */
   cmi5Mode?: boolean;
+  /** When set, every send method rejects with the returned Error without hitting the network. */
+  unavailableReason?: () => Error;
 }
 
 interface SendOutcome {
@@ -67,7 +66,7 @@ interface SendOutcome {
   error?: Error;
 }
 
-const STATEMENT_RETRY_ATTEMPTS = 3;
+const STATEMENT_RETRY_ATTEMPTS = RETRY_ATTEMPTS;
 /**
  * Soft cap on the number of in-flight statements queued behind the head of
  * the chain. We log a one-time warning when the queue grows past this so
@@ -106,6 +105,9 @@ export class XAPIPublisher {
   readonly #sessionId: string;
   readonly #cmi5Mode: boolean;
 
+  // When set, every send method short-circuits with a rejected promise.
+  readonly #unavailableReason: (() => Error) | null;
+
   // Auth — string or resolver. Cached after first resolution.
   readonly #authValue: string | (() => string | Promise<string>);
   #cachedAuth: string | null = null;
@@ -149,6 +151,7 @@ export class XAPIPublisher {
     this.#authValue = opts.auth;
     this.#actorValue = opts.actor;
     this.#sessionId = opts.sessionId ?? uuidv4();
+    this.#unavailableReason = opts.unavailableReason ?? null;
 
     if (typeof this.#actorValue !== 'function') {
       this.#cachedActor = this.#actorValue;
@@ -298,6 +301,9 @@ export class XAPIPublisher {
     partial: PartialStatement,
     options?: SendStatementOptions & { id?: string }
   ): Promise<SendStatementResult> {
+    if (this.#unavailableReason) {
+      return Promise.reject(this.#unavailableReason());
+    }
     try {
       validatePartialStatement(partial);
     } catch (err) {
@@ -332,6 +338,9 @@ export class XAPIPublisher {
     statementOrBatch: Statement | Statement[],
     options?: SendStatementOptions
   ): Promise<DestinationOutcome> {
+    if (this.#unavailableReason) {
+      return Promise.reject(this.#unavailableReason());
+    }
     if (this.#queueDepth >= QUEUE_DEPTH_SATURATED) {
       return Promise.resolve<DestinationOutcome>({
         endpoint: this.#endpoint,
@@ -449,7 +458,7 @@ export class XAPIPublisher {
         }
         if (isFinal) return outcome;
         return new Promise<void>((r) =>
-          setTimeout(r, 100 * Math.pow(2, n))
+          setTimeout(r, backoffMs(n))
         ).then(() => attempt(n + 1));
       });
     };

package/src/runtime/xapi/setup.ts

@@ -42,28 +42,21 @@ class XAPIDevFallbackError extends Error {
 }
 
 /**
- * Build a stub publisher whose sends reject with `error`. Used for both
- * dev-fallback paths: cmi5 `endpoint: 'lms'` with no launch params, and
- * SCORM explicit endpoints that depend on a learner identity the dev
- * fallback can't synthesize. The placeholder publisher carries a static
- * actor so its constructor invariants hold and `XAPIClient.buildStatement`
- * can run without throwing — only the network-bound methods reject.
+ * Build a stub publisher whose sends reject with the supplied error. Used for
+ * both dev-fallback paths: cmi5 `endpoint: 'lms'` with no launch params, and
+ * SCORM explicit endpoints that depend on a learner identity the dev fallback
+ * can't synthesize. The placeholder carries a static actor so the constructor
+ * invariants hold and `XAPIClient.buildStatement` can run without throwing —
+ * the `unavailableReason` opt makes only the network-bound methods reject.
  */
 function makeRejectingPublisher(error: () => Error): XAPIPublisher {
-  const pub = new XAPIPublisher({
+  return new XAPIPublisher({
     endpoint: 'http://localhost/__tessera_dev_fallback__/',
     auth: '',
     actor: { mbox: 'mailto:nobody@example.invalid', objectType: 'Agent' },
     activityId: 'http://localhost/__tessera_dev_fallback__',
+    unavailableReason: error,
   });
-  // The static actor is cached at construction so getActor()/buildStatement
-  // work without a separate init() call. We only override the methods that
-  // would otherwise hit the network so author code surfaces the explicit
-  // error rather than silently no-oping.
-  const reject = (): Promise<never> => Promise.reject(error());
-  (pub as any).sendStatement = reject;
-  (pub as any).enqueueBuilt = reject;
-  return pub;
 }
 
 function makeDevFallbackPublisher(): XAPIPublisher {

package/styles/layout.css

@@ -315,6 +315,27 @@
   text-align: center;
 }
 
+/* ---- Buttons ---- */
+.tessera-btn-primary {
+  background-color: var(--tessera-primary);
+  color: #ffffff;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  min-height: 44px;
+  font-family: var(--tessera-font-family);
+  transition: background-color var(--tessera-transition-fast), opacity var(--tessera-transition-fast);
+}
+
+.tessera-btn-primary:hover:not(:disabled) {
+  background-color: var(--tessera-primary-dark);
+}
+
+.tessera-btn-primary:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
 /* ---- Error Page ---- */
 .tessera-error {
   text-align: center;
@@ -338,16 +359,6 @@
   padding: var(--tessera-spacing-sm) var(--tessera-spacing-lg);
   font-size: 0.875rem;
   font-weight: 600;
-  color: #ffffff;
-  background-color: var(--tessera-primary);
-  border: none;
-  border-radius: 6px;
-  cursor: pointer;
-  transition: background-color var(--tessera-transition-fast);
-}
-
-.tessera-error-retry:hover {
-  background-color: var(--tessera-primary-dark);
 }
 
 /* ---- Responsive: Tablet (max-width: 1024px) ---- */

package/styles/theme.css

@@ -9,7 +9,11 @@
   --tessera-bg-secondary: #f9fafb;
   --tessera-border: #e5e7eb;
   --tessera-success: #16a34a;
+  --tessera-success-bg: color-mix(in srgb, var(--tessera-success) 8%, transparent);
+  --tessera-success-border: color-mix(in srgb, var(--tessera-success) 25%, transparent);
   --tessera-error: #dc2626;
+  --tessera-error-bg: color-mix(in srgb, var(--tessera-error) 8%, transparent);
+  --tessera-error-border: color-mix(in srgb, var(--tessera-error) 25%, transparent);
   --tessera-warning: #d97706;
 
   /* Typography */