tessera-learn 0.0.1

package/src/runtime/adapters/retry.ts

@@ -0,0 +1,284 @@
+/**
+ * Optional callback that surfaces the LMS's last-error code/message after
+ * a failed call, so warning logs can name the actual cause instead of a
+ * generic "LMS call failed".
+ */
+export interface LMSErrorReporter {
+  /** Last error from `LMSGetLastError` / `GetLastError`. */
+  code(): string;
+  /** Human-readable message from `LMSGetErrorString` / `GetErrorString`. */
+  message(code: string): string;
+}
+
+/**
+ * Retry wrapper for LMS API calls.
+ * Retries up to maxRetries times with exponential backoff.
+ * Returns true if the call eventually succeeded, false otherwise.
+ *
+ * If `errorReporter` is provided, the SCORM `GetLastError` /
+ * `GetErrorString` pair is read after each failure and surfaced in the
+ * final warning so production triage can name the real failure
+ * (e.g., "201 Invalid argument error" or "405 Incorrect Data Type").
+ *
+ * Note: During page unload (pagehide/beforeunload), only the first
+ * synchronous attempt will execute — async retries with setTimeout
+ * won't run because the page is being torn down. This is acceptable
+ * for SCORM adapters where the underlying API calls are synchronous.
+ */
+export async function withRetry(
+  fn: () => any,
+  maxRetries = 3,
+  errorReporter?: LMSErrorReporter,
+  context?: string
+): Promise<boolean> {
+  let lastErrCode = '';
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      const result = fn();
+      if (result !== false && result !== 'false') return true;
+    } catch {
+      // API call threw — treat as failure
+    }
+    if (errorReporter) {
+      try { lastErrCode = errorReporter.code(); } catch {}
+    }
+    if (attempt < maxRetries - 1) {
+      await new Promise((r) => setTimeout(r, 100 * Math.pow(2, attempt)));
+    }
+  }
+  let detail = '';
+  if (errorReporter && lastErrCode && lastErrCode !== '0') {
+    try {
+      const msg = errorReporter.message(lastErrCode);
+      detail = ` (LMS error ${lastErrCode}${msg ? `: ${msg}` : ''})`;
+    } catch {}
+  }
+  const ctx = context ? ` [${context}]` : '';
+  console.warn(
+    `Tessera: LMS call failed after retries${ctx}${detail}, continuing without persistence`
+  );
+  return false;
+}
+
+/**
+ * Synchronous single-attempt LMS call. Used during page unload
+ * where async retries cannot run.
+ */
+export function callSync(fn: () => any): boolean {
+  try {
+    const result = fn();
+    return result !== false && result !== 'false';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Sequential write queue for LMS operations.
+ * Enqueues operations and flushes them sequentially with retry.
+ * If an operation fails after retries, the queue stops and retries
+ * the failed operation on the next flush trigger.
+ */
+interface QueueEntry {
+  fn: () => any;
+  context?: string;
+}
+
+export class WriteQueue {
+  #queue: QueueEntry[] = [];
+  #flushing = false;
+  #aborted = false;
+  /**
+   * The entry that the async flush has shifted off the queue and is
+   * currently awaiting a retry on. drainSync needs to know about this so
+   * it can re-run the entry synchronously — otherwise an entry caught
+   * mid-backoff at unload time vanishes silently.
+   */
+  #inFlight: QueueEntry | null = null;
+
+  errorReporter?: LMSErrorReporter;
+
+  /**
+   * Enqueue an operation and trigger a flush.
+   */
+  enqueue(fn: () => any, context?: string): void {
+    this.#queue.push({ fn, context });
+    if (!this.#flushing) {
+      this.#flush();
+    }
+  }
+
+  /**
+   * Flush the queue sequentially. If an operation fails after retries,
+   * re-insert it at the front and stop — retry on next trigger.
+   *
+   * Retry is inlined (not delegated to `withRetry`) so we can mark
+   * `#inFlight` *only* while awaiting a backoff. drainSync re-runs an
+   * in-flight entry synchronously, which is only safe when the current
+   * attempt has failed and the next attempt is what we're waiting on.
+   */
+  async #flush(): Promise<void> {
+    if (this.#flushing) return;
+    this.#flushing = true;
+    this.#aborted = false;
+
+    const MAX_ATTEMPTS = 3;
+
+    while (this.#queue.length > 0) {
+      if (this.#aborted) {
+        this.#flushing = false;
+        return;
+      }
+
+      const entry = this.#queue.shift()!;
+      let succeeded = false;
+      let lastErrCode = '';
+
+      for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        let ok = false;
+        try {
+          const result = entry.fn();
+          ok = result !== false && result !== 'false';
+        } catch {
+          // API call threw — treat as failure
+        }
+        if (ok) {
+          succeeded = true;
+          break;
+        }
+        if (this.errorReporter) {
+          try { lastErrCode = this.errorReporter.code(); } catch {}
+        }
+        if (attempt < MAX_ATTEMPTS - 1) {
+          // The next attempt is gated on a backoff timer that won't fire
+          // during page unload. Mark in-flight so drainSync can re-run
+          // the entry synchronously if it interrupts here.
+          this.#inFlight = entry;
+          await new Promise((r) => setTimeout(r, 100 * Math.pow(2, attempt)));
+          this.#inFlight = null;
+          if (this.#aborted) {
+            this.#flushing = false;
+            return;
+          }
+        }
+      }
+
+      if (!succeeded) {
+        let detail = '';
+        if (this.errorReporter && lastErrCode && lastErrCode !== '0') {
+          try {
+            const msg = this.errorReporter.message(lastErrCode);
+            detail = ` (LMS error ${lastErrCode}${msg ? `: ${msg}` : ''})`;
+          } catch {}
+        }
+        const ctx = entry.context ? ` [${entry.context}]` : '';
+        console.warn(
+          `Tessera: LMS call failed after retries${ctx}${detail}, continuing without persistence`
+        );
+        this.#queue.unshift(entry);
+        this.#flushing = false;
+        return;
+      }
+    }
+
+    this.#flushing = false;
+  }
+
+  /**
+   * Synchronously drain the queue (best-effort, single attempt each).
+   * Used during page unload where async operations cannot complete.
+   * Aborts any in-progress async flush and re-runs its in-flight entry
+   * synchronously (the awaited backoff timer won't fire during unload).
+   */
+  drainSync(): void {
+    this.#aborted = true;
+    this.#flushing = false;
+    if (this.#inFlight) {
+      // The async flush's withRetry was suspended at a setTimeout backoff
+      // that won't fire before the page tears down. Run the entry once
+      // synchronously so its write isn't lost. The async flush will see
+      // the abort flag when (if) it ever resumes and exit cleanly.
+      const entry = this.#inFlight;
+      this.#inFlight = null;
+      callSync(entry.fn);
+    }
+    while (this.#queue.length > 0) {
+      const entry = this.#queue.shift()!;
+      callSync(entry.fn);
+    }
+  }
+
+  get pending(): number {
+    return this.#queue.length;
+  }
+}
+
+/**
+ * Walk the window.opener and window.parent chains looking for an LMS API object.
+ * Shared by SCORM 1.2 (property "API") and SCORM 2004 (property "API_1484_11").
+ * Returns null if not found within 10 levels or a cross-origin boundary is hit.
+ */
+export function findLMSAPI(propName: string): unknown {
+  function scan(win: Window): unknown {
+    for (let i = 0; i < 10; i++) {
+      try {
+        const value = (win as unknown as Record<string, unknown>)[propName];
+        if (value) return value;
+      } catch {
+        // Cross-origin frame — stop
+        return null;
+      }
+      if (win.parent === win) break;
+      try {
+        win = win.parent;
+      } catch {
+        // Cross-origin frame — stop
+        break;
+      }
+    }
+    return null;
+  }
+
+  // Check window.opener chain first (popup launch pattern)
+  if (window.opener) {
+    const api = scan(window.opener as Window);
+    if (api) return api;
+  }
+
+  // Check window.parent chain (iframe launch pattern)
+  return scan(window);
+}
+
+/**
+ * Format integer seconds as SCORM 1.2 `CMITimespan` (HHHH:MM:SS.SS).
+ *
+ * `DurationTracker.sessionSeconds` always feeds integer seconds via
+ * `Math.floor`, so the centisecond field is always `.00`. The format
+ * still includes it because `CMITimespan` is defined that way and some
+ * older LMS importers reject the bare HHHH:MM:SS form.
+ */
+export function formatHHMMSS(totalSeconds: number): string {
+  const whole = Math.floor(totalSeconds);
+  const hours = Math.floor(whole / 3600);
+  const minutes = Math.floor((whole % 3600) / 60);
+  const seconds = whole % 60;
+  const hh = String(hours).padStart(4, '0');
+  const mm = String(minutes).padStart(2, '0');
+  const ss = String(seconds).padStart(2, '0');
+  return `${hh}:${mm}:${ss}.00`;
+}
+
+/**
+ * Format seconds as ISO 8601 duration: PT1H30M45S
+ */
+export function formatISO8601Duration(totalSeconds: number): string {
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  let result = 'PT';
+  if (hours > 0) result += `${hours}H`;
+  if (minutes > 0) result += `${minutes}M`;
+  if (seconds > 0 || result === 'PT') result += `${seconds}S`;
+  return result;
+}

package/src/runtime/adapters/scorm12.ts

@@ -0,0 +1,172 @@
+import type { PersistenceAdapter, SavedState } from '../persistence.js';
+import type { Interaction } from '../interaction.js';
+import { buildScormInteractionFields, scorm12Type } from '../interaction-format.js';
+import { WriteQueue, callSync, withRetry, formatHHMMSS } from './retry.js';
+
+/**
+ * SCORM 1.2 API interface.
+ */
+export interface SCORM12API {
+  LMSInitialize(param: string): string;
+  LMSFinish(param: string): string;
+  LMSGetValue(element: string): string;
+  LMSSetValue(element: string, value: string): string;
+  LMSCommit(param: string): string;
+  LMSGetLastError(): string;
+  LMSGetErrorString(errorCode: string): string;
+  LMSGetDiagnostic(errorCode: string): string;
+}
+
+/**
+ * SCORM 1.2 persistence adapter.
+ *
+ * Uses a sequential write queue for all LMS SetValue/Commit calls.
+ * On terminate, the queue is drained synchronously (single attempt)
+ * since async retries cannot complete during page unload.
+ */
+export class SCORM12Adapter implements PersistenceAdapter {
+  #api: SCORM12API;
+  #queue = new WriteQueue();
+  #state: SavedState | null = null;
+  #terminated = false;
+
+  // SCORM 1.2 combines completion and success into a single lesson_status field
+  #completionStatus: string = 'incomplete';
+  #successStatus: string | null = null;
+  #interactionCount = 0;
+
+  constructor(api: SCORM12API) {
+    this.#api = api;
+    // Wire up GetLastError/GetErrorString so retry warnings can name the
+    // real LMS failure (e.g. "201 Invalid argument error") instead of a
+    // generic "LMS call failed" — production triage needs the code.
+    this.#queue.errorReporter = {
+      code: () => this.#api.LMSGetLastError(),
+      message: (c) => this.#api.LMSGetErrorString(c),
+    };
+  }
+
+  /** Expose the underlying SCORM 1.2 API so xAPI actor synthesis can read learner fields. */
+  getAPI(): SCORM12API {
+    return this.#api;
+  }
+
+  async init(): Promise<void> {
+    await withRetry(() => this.#api.LMSInitialize(''));
+
+    try {
+      const raw = this.#api.LMSGetValue('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 (the LMS uses n
+    // as the array key, not an upsert field).
+    try {
+      const count = this.#api.LMSGetValue('cmi.interactions._count');
+      const n = parseInt(count, 10);
+      if (Number.isFinite(n) && n >= 0) this.#interactionCount = n;
+    } catch {
+      // Some LMSes throw on _count when no interactions exist — fall back to 0.
+    }
+  }
+
+  getState(): SavedState | null {
+    return this.#state;
+  }
+
+  saveState(state: SavedState): void {
+    this.#state = state;
+    const json = JSON.stringify(state);
+    this.#queue.enqueue(() => this.#api.LMSSetValue('cmi.suspend_data', json));
+  }
+
+  setScore(score: number): void {
+    this.#queue.enqueue(() =>
+      this.#api.LMSSetValue('cmi.core.score.raw', String(score))
+    );
+    this.#queue.enqueue(() =>
+      this.#api.LMSSetValue('cmi.core.score.min', '0')
+    );
+    this.#queue.enqueue(() =>
+      this.#api.LMSSetValue('cmi.core.score.max', '100')
+    );
+  }
+
+  setCompletionStatus(status: 'incomplete' | 'complete'): void {
+    this.#completionStatus = status === 'complete' ? 'completed' : 'incomplete';
+    this.#flushLessonStatus();
+  }
+
+  setSuccessStatus(status: 'passed' | 'failed' | 'unknown'): void {
+    // SCORM 1.2 has no "unknown" lesson_status — clear the success override
+    // so completion status drives lesson_status until a real result is known.
+    this.#successStatus = status === 'unknown' ? null : status;
+    this.#flushLessonStatus();
+  }
+
+  #flushLessonStatus(): void {
+    // Success status takes priority — it's the more specific status
+    const value = this.#successStatus ?? this.#completionStatus;
+    this.#queue.enqueue(() =>
+      this.#api.LMSSetValue('cmi.core.lesson_status', value)
+    );
+  }
+
+  setDuration(seconds: number): void {
+    const formatted = formatHHMMSS(seconds);
+    this.#queue.enqueue(() =>
+      this.#api.LMSSetValue('cmi.core.session_time', formatted)
+    );
+  }
+
+  setExit(mode: 'suspend' | 'normal'): void {
+    // SCORM 1.2 §4.2.2 vocabulary: time-out, suspend, logout, "" (normal).
+    // We only map 'suspend' and the empty/normal case.
+    const value = mode === 'suspend' ? 'suspend' : '';
+    this.#queue.enqueue(() => this.#api.LMSSetValue('cmi.core.exit', value));
+  }
+
+  reportInteraction(
+    questionId: string,
+    interaction: Interaction,
+    correct: boolean | null
+  ): void {
+    const n = this.#interactionCount++;
+    const fields = buildScormInteractionFields(
+      `cmi.interactions.${n}`,
+      questionId,
+      interaction,
+      correct,
+      {
+        responseField: 'student_response',
+        timestampField: 'time',
+        timestamp: new Date().toTimeString().slice(0, 8),
+        typeValue: scorm12Type(interaction.type),
+        resultLabels: { correct: 'correct', incorrect: 'wrong' },
+      }
+    );
+    for (const [key, value] of fields) {
+      this.#queue.enqueue(() => this.#api.LMSSetValue(key, value));
+    }
+  }
+
+  commit(): void {
+    this.#queue.enqueue(() => this.#api.LMSCommit(''));
+  }
+
+  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 finish synchronously.
+    this.#queue.drainSync();
+    callSync(() => this.#api.LMSCommit(''));
+    callSync(() => this.#api.LMSFinish(''));
+  }
+}

package/src/runtime/adapters/scorm2004.ts

@@ -0,0 +1,162 @@
+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';
+
+/**
+ * SCORM 2004 API interface.
+ */
+export interface SCORM2004API {
+  Initialize(param: string): string;
+  Terminate(param: string): string;
+  GetValue(element: string): string;
+  SetValue(element: string, value: string): string;
+  Commit(param: string): string;
+  GetLastError(): string;
+  GetErrorString(errorCode: string): string;
+  GetDiagnostic(errorCode: string): string;
+}
+
+/**
+ * SCORM 2004 persistence adapter.
+ *
+ * Uses a sequential write queue for all LMS SetValue/Commit calls.
+ * 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;
+
+  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));
+  }
+
+  setScore(score: number): void {
+    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))
+    );
+  }
+
+  // Note: cmi.completion_threshold and cmi.scaled_passing_score are typically
+  // set by the LMS, not the SCO. Tessera manages completion and passing
+  // 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)
+    );
+  }
+
+  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)
+    );
+  }
+
+  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(''));
+  }
+}

package/src/runtime/adapters/web.ts

@@ -0,0 +1,62 @@
+import type { PersistenceAdapter, SavedState } from '../persistence.js';
+import type { CourseConfig } from '../types.js';
+import type { Interaction } from '../interaction.js';
+import { slugify } from '../slugify.js';
+
+/**
+ * Web persistence adapter — stores course state in localStorage.
+ * Used for standalone web deployments (no LMS).
+ */
+export class WebAdapter implements PersistenceAdapter {
+  #storageKey: string;
+  #state: SavedState | null = null;
+
+  constructor(config: CourseConfig) {
+    const courseId = slugify(config.title || '') || 'tessera-course';
+    this.#storageKey = `tessera-${courseId}`;
+  }
+
+  async init(): Promise<void> {
+    try {
+      const raw = localStorage.getItem(this.#storageKey);
+      if (raw) {
+        this.#state = JSON.parse(raw);
+      }
+    } catch {
+      // Corrupted data or localStorage unavailable — start fresh
+      this.#state = null;
+    }
+  }
+
+  getState(): SavedState | null {
+    return this.#state;
+  }
+
+  saveState(state: SavedState): void {
+    this.#state = state;
+    try {
+      localStorage.setItem(this.#storageKey, JSON.stringify(state));
+    } catch {
+      // localStorage full or unavailable — silently fail
+      console.warn('Tessera: Failed to save state to localStorage');
+    }
+  }
+
+  // No-ops for web adapter — these are used by LMS adapters
+  setScore(_score: number): void {}
+  setCompletionStatus(_status: 'incomplete' | 'complete'): void {}
+  setSuccessStatus(_status: 'passed' | 'failed' | 'unknown'): void {}
+  setDuration(_seconds: number): void {}
+  setExit(_mode: 'suspend' | 'normal'): void {}
+  reportInteraction(
+    _questionId: string,
+    _interaction: Interaction,
+    _correct: boolean | null
+  ): void {
+    // Web adapter has no external LMS; learner interaction data lives only
+    // in memory. Authors who want to persist per-question state can use
+    // `usePersistence(key)` which writes into SavedState.u.
+  }
+  commit(): void {}
+  terminate(): void {}
+}