tessera-learn 0.0.5 → 0.0.7

package/src/runtime/adapters/scorm-base.ts

@@ -1,34 +1,33 @@
 import type { PersistenceAdapter, SavedState } from '../persistence.js';
 import type { Interaction } from '../interaction.js';
-import { buildScormInteractionFields } from '../interaction-format.js';
-import { WriteQueue, callSync, withRetry } from './retry.js';
+import {
+  buildScormInteractionFields,
+  type InteractionFormat,
+} from '../interaction-format.js';
+import { WriteQueue, callSyncOrWarn, withRetry } from './retry.js';
+import type { LMSErrorReporter } from './retry.js';
 
-/** Per-version differences shared between SCORM 1.2 and SCORM 2004 adapters. */
+/**
+ * Per-version differences shared between SCORM 1.2 and SCORM 2004 adapters.
+ *
+ * `suspendDataLimit` is per-spec characters: SCORM 1.2 RTE §3.4.5.2 = 4096;
+ * SCORM 2004 4E §4.2 = 64000. The `LMS*`-prefixed (1.2) vs bare (2004)
+ * method names are abstracted here so the base class can stay version-
+ * agnostic.
+ */
 export interface ScormDialect<TApi> {
-  /** SCORM 1.2: `cmi.core.session_time`. SCORM 2004: `cmi.session_time`. */
   sessionTimeKey: string;
-  /** Format `seconds` for the session-time field — HHMMSS for 1.2, ISO8601 for 2004. */
   formatDuration(seconds: number): string;
-  /**
-   * Per-spec maximum byte length for `cmi.suspend_data` (SCORM 1.2 RTE
-   * §3.4.5.2 = 4096; SCORM 2004 4E §4.2 = 64000). Used by `saveState` to
-   * warn once when the serialized payload would be silently truncated by
-   * the LMS. Treated as "characters" since SCORM data-model lengths are
-   * specified in characters and Tessera stores ASCII-safe JSON.
-   */
   suspendDataLimit: number;
-  /** Human label for the limit warning, e.g. "SCORM 1.2 (4096 chars)". */
   suspendDataLimitLabel: string;
-  /** Per-interaction-row field config passed to `buildScormInteractionFields`. */
   interactionFields: {
     responseField: 'student_response' | 'learner_response';
     timestampField: 'time' | 'timestamp';
-    /** Build the per-call timestamp string (HH:MM:SS for 1.2, ISO8601 for 2004). */
     timestamp(): string;
     typeValue(type: Interaction['type']): string;
     resultLabels: { correct: string; incorrect: string };
+    format: InteractionFormat;
   };
-  /** API method wrappers — abstract over the `LMS*`-prefixed and bare names. */
   initialize(api: TApi): string;
   terminate(api: TApi): string;
   getValue(api: TApi, key: string): string;
@@ -36,12 +35,14 @@ export interface ScormDialect<TApi> {
   commit(api: TApi): string;
   getLastError(api: TApi): string;
   getErrorString(api: TApi, code: string): string;
+  getDiagnostic?(api: TApi, code: string): string;
 }
 
 export abstract class BaseScormAdapter<TApi> implements PersistenceAdapter {
   protected readonly api: TApi;
   protected readonly dialect: ScormDialect<TApi>;
   protected readonly queue = new WriteQueue();
+  protected readonly errorReporter: LMSErrorReporter;
   #state: SavedState | null = null;
   #terminated = false;
   #suspendOverflowWarned = false;
@@ -50,41 +51,76 @@ export abstract class BaseScormAdapter<TApi> implements PersistenceAdapter {
   constructor(api: TApi, dialect: ScormDialect<TApi>) {
     this.api = api;
     this.dialect = dialect;
-    // 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 = {
+    this.errorReporter = {
       code: () => this.dialect.getLastError(this.api),
       message: (c) => this.dialect.getErrorString(this.api, c),
+      diagnostic: this.dialect.getDiagnostic
+        ? (c) => this.dialect.getDiagnostic!(this.api, c)
+        : undefined,
     };
+    this.queue.errorReporter = this.errorReporter;
   }
 
-  /** Expose the underlying SCORM API so xAPI actor synthesis can read learner fields. */
+  /** Exposed for xAPI actor synthesis (reads learner fields off the API). */
   getAPI(): TApi {
     return this.api;
   }
 
   async init(): Promise<void> {
-    await withRetry(() => this.dialect.initialize(this.api));
+    const initialized = await withRetry(
+      () => this.dialect.initialize(this.api),
+      undefined,
+      this.errorReporter,
+      'Initialize'
+    );
+    if (!initialized) {
+      console.warn(
+        'Tessera: LMS Initialize failed — all subsequent persistence calls will fail with error 301 (Not Initialized). Reload the launch from the LMS.'
+      );
+      return;
+    }
 
+    let raw = '';
     try {
-      const raw = this.dialect.getValue(this.api, 'cmi.suspend_data');
-      if (raw && raw.trim()) {
+      raw = this.dialect.getValue(this.api, 'cmi.suspend_data');
+    } catch (err) {
+      console.warn(
+        'Tessera: LMS threw on GetValue(cmi.suspend_data); resume disabled for this launch',
+        err
+      );
+    }
+    if (raw && raw.trim()) {
+      try {
         this.#state = JSON.parse(raw);
+      } catch (err) {
+        console.warn(
+          'Tessera: cmi.suspend_data is not valid JSON; resume disabled for this launch (the LMS may have truncated a prior write)',
+          err
+        );
+        this.#state = null;
       }
-    } 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).
+    // n indexing must continue from _count — restarting at 0 would overwrite
+    // the prior session's records (the LMS uses n as the array key).
+    let countRaw = '';
     try {
-      const count = this.dialect.getValue(this.api, '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.
+      countRaw = this.dialect.getValue(this.api, 'cmi.interactions._count');
+    } catch (err) {
+      console.warn(
+        'Tessera: LMS threw on GetValue(cmi.interactions._count); new interactions will be written from index 0 and may overwrite prior session records',
+        err
+      );
+      return;
+    }
+    if (countRaw === '' || countRaw === '0') return;
+    const n = parseInt(countRaw, 10);
+    if (Number.isFinite(n) && n >= 0) {
+      this.interactionCount = n;
+    } else {
+      console.warn(
+        `Tessera: LMS returned non-numeric cmi.interactions._count="${countRaw}"; new interactions will be written from index 0 and may overwrite prior session records`
+      );
     }
   }
 
@@ -108,15 +144,18 @@ export abstract class BaseScormAdapter<TApi> implements PersistenceAdapter {
           `larger-limit standard (scorm2004/cmi5).`
       );
     }
-    this.queue.enqueue(() =>
-      this.dialect.setValue(this.api, 'cmi.suspend_data', json)
+    this.queue.enqueue(
+      () => this.dialect.setValue(this.api, 'cmi.suspend_data', json),
+      'cmi.suspend_data'
     );
   }
 
   setDuration(seconds: number): void {
     const formatted = this.dialect.formatDuration(seconds);
-    this.queue.enqueue(() =>
-      this.dialect.setValue(this.api, this.dialect.sessionTimeKey, formatted)
+    this.queue.enqueue(
+      () =>
+        this.dialect.setValue(this.api, this.dialect.sessionTimeKey, formatted),
+      this.dialect.sessionTimeKey
     );
   }
 
@@ -137,29 +176,34 @@ export abstract class BaseScormAdapter<TApi> implements PersistenceAdapter {
         timestamp: this.dialect.interactionFields.timestamp(),
         typeValue: this.dialect.interactionFields.typeValue(interaction.type),
         resultLabels: this.dialect.interactionFields.resultLabels,
+        format: this.dialect.interactionFields.format,
       }
     );
     for (const [key, value] of fields) {
-      this.queue.enqueue(() => this.dialect.setValue(this.api, key, value));
+      this.queue.enqueue(
+        () => this.dialect.setValue(this.api, key, value),
+        key
+      );
     }
   }
 
   commit(): void {
-    this.queue.enqueue(() => this.dialect.commit(this.api));
+    this.queue.enqueue(() => this.dialect.commit(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 finish synchronously.
+    // Async retries can't run during page unload — drain + commit + finish synchronously.
     this.queue.drainSync();
-    callSync(() => this.dialect.commit(this.api));
-    callSync(() => this.dialect.terminate(this.api));
+    callSyncOrWarn(() => this.dialect.commit(this.api), 'Commit', this.errorReporter);
+    callSyncOrWarn(
+      () => this.dialect.terminate(this.api),
+      'Terminate',
+      this.errorReporter
+    );
   }
 
-  // The four operations that genuinely diverge between SCORM versions.
   abstract setScore(score: number): void;
   abstract setCompletionStatus(status: 'incomplete' | 'complete'): void;
   abstract setSuccessStatus(status: 'passed' | 'failed' | 'unknown'): void;

package/src/runtime/adapters/scorm12.ts

@@ -1,6 +1,10 @@
-import { scorm12Type } from '../interaction-format.js';
+import {
+  SCORM12_INTERACTION_FORMAT,
+  scorm12Type,
+} from '../interaction-format.js';
+import type { SavedState } from '../persistence.js';
 import { BaseScormAdapter, type ScormDialect } from './scorm-base.js';
-import { formatHHMMSS } from './retry.js';
+import { formatHHMMSS, formatReal107 } from './retry.js';
 
 /**
  * SCORM 1.2 API interface.
@@ -27,6 +31,7 @@ const SCORM12_DIALECT: ScormDialect<SCORM12API> = {
     timestamp: () => new Date().toTimeString().slice(0, 8),
     typeValue: (t) => scorm12Type(t),
     resultLabels: { correct: 'correct', incorrect: 'wrong' },
+    format: SCORM12_INTERACTION_FORMAT,
   },
   initialize: (api) => api.LMSInitialize(''),
   terminate: (api) => api.LMSFinish(''),
@@ -35,6 +40,7 @@ const SCORM12_DIALECT: ScormDialect<SCORM12API> = {
   commit: (api) => api.LMSCommit(''),
   getLastError: (api) => api.LMSGetLastError(),
   getErrorString: (api, code) => api.LMSGetErrorString(code),
+  getDiagnostic: (api, code) => api.LMSGetDiagnostic(code),
 };
 
 /**
@@ -57,12 +63,29 @@ export class SCORM12Adapter extends BaseScormAdapter<SCORM12API> {
     super(api, SCORM12_DIALECT);
   }
 
+  saveState(state: SavedState): void {
+    super.saveState(state);
+    // §3.4.5.3 — bookmark for LMS "Resume from page N" affordances.
+    this.queue.enqueue(
+      () =>
+        this.api.LMSSetValue('cmi.core.lesson_location', String(state.b)),
+      'cmi.core.lesson_location'
+    );
+  }
+
   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.raw', formatReal107(score)),
+      'cmi.core.score.raw'
+    );
+    this.queue.enqueue(
+      () => this.api.LMSSetValue('cmi.core.score.min', '0'),
+      'cmi.core.score.min'
+    );
+    this.queue.enqueue(
+      () => this.api.LMSSetValue('cmi.core.score.max', '100'),
+      'cmi.core.score.max'
     );
-    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 {
@@ -78,17 +101,19 @@ export class SCORM12Adapter extends BaseScormAdapter<SCORM12API> {
   }
 
   #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)
+    this.queue.enqueue(
+      () => this.api.LMSSetValue('cmi.core.lesson_status', value),
+      'cmi.core.lesson_status'
     );
   }
 
   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));
+    this.queue.enqueue(
+      () => this.api.LMSSetValue('cmi.core.exit', value),
+      'cmi.core.exit'
+    );
   }
 }

package/src/runtime/adapters/scorm2004.ts

@@ -1,9 +1,12 @@
+import { SCORM2004_INTERACTION_FORMAT } from '../interaction-format.js';
+import type { SavedState } from '../persistence.js';
 import { BaseScormAdapter, type ScormDialect } from './scorm-base.js';
-import { formatISO8601Duration } from './retry.js';
+import {
+  formatISO8601Duration,
+  formatISO8601Timestamp,
+  formatReal107,
+} from './retry.js';
 
-/**
- * SCORM 2004 API interface.
- */
 export interface SCORM2004API {
   Initialize(param: string): string;
   Terminate(param: string): string;
@@ -23,10 +26,11 @@ const SCORM2004_DIALECT: ScormDialect<SCORM2004API> = {
   interactionFields: {
     responseField: 'learner_response',
     timestampField: 'timestamp',
-    timestamp: () => new Date().toISOString(),
+    timestamp: () => formatISO8601Timestamp(new Date()),
     // SCORM 2004 accepts the canonical interaction `type` strings unchanged.
     typeValue: (t) => t,
     resultLabels: { correct: 'correct', incorrect: 'incorrect' },
+    format: SCORM2004_INTERACTION_FORMAT,
   },
   initialize: (api) => api.Initialize(''),
   terminate: (api) => api.Terminate(''),
@@ -35,49 +39,148 @@ const SCORM2004_DIALECT: ScormDialect<SCORM2004API> = {
   commit: (api) => api.Commit(''),
   getLastError: (api) => api.GetLastError(),
   getErrorString: (api, code) => api.GetErrorString(code),
+  getDiagnostic: (api, code) => api.GetDiagnostic(code),
 };
 
+/** SCORM 2004 4E §4.2.1.5 cmi.mode vocabulary. */
+export type SCORM2004Mode = 'browse' | 'normal' | 'review';
+
 /**
- * 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.
+ * Per §4.2.1.5, the SCO MUST NOT alter the learner record in `browse` or
+ * `review` mode — every write below is gated on `#mode === 'normal'`.
+ * `#masteryScore` (§4.2.4.3) and `#completionThreshold` (§4.2.4.4) are
+ * LMS-supplied thresholds in [0,1].
  */
 export class SCORM2004Adapter extends BaseScormAdapter<SCORM2004API> {
+  #mode: SCORM2004Mode = 'normal';
+  #masteryScore: number | null = null;
+  #completionThreshold: number | null = null;
+
   constructor(api: SCORM2004API) {
     super(api, SCORM2004_DIALECT);
   }
 
+  async init(): Promise<void> {
+    await super.init();
+    this.#mode = this.#readMode();
+    this.#masteryScore = this.#readScaledThreshold('cmi.scaled_passing_score');
+    this.#completionThreshold = this.#readScaledThreshold(
+      'cmi.completion_threshold'
+    );
+  }
+
+  getLaunchMode(): SCORM2004Mode {
+    return this.#mode;
+  }
+
+  /** Read by App.svelte to override `course.config.js scoring.passingScore`. */
+  getMasteryScore(): number | null {
+    return this.#masteryScore;
+  }
+
+  getCompletionThreshold(): number | null {
+    return this.#completionThreshold;
+  }
+
+  #readMode(): SCORM2004Mode {
+    try {
+      const v = this.api.GetValue('cmi.mode');
+      if (v === 'browse' || v === 'review' || v === 'normal') return v;
+    } catch {}
+    return 'normal';
+  }
+
+  #readScaledThreshold(key: string): number | null {
+    let raw = '';
+    try {
+      raw = this.api.GetValue(key);
+    } catch {
+      return null;
+    }
+    if (!raw) return null;
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0 && n <= 1) return n;
+    return null;
+  }
+
+  saveState(state: SavedState): void {
+    if (this.#mode !== 'normal') return;
+    super.saveState(state);
+    // §4.2.1.4 — bookmark for LMS "Resume from page N" affordances.
+    this.queue.enqueue(
+      () => this.api.SetValue('cmi.location', String(state.b)),
+      'cmi.location'
+    );
+  }
+
+  setDuration(seconds: number): void {
+    if (this.#mode !== 'normal') return;
+    super.setDuration(seconds);
+  }
+
+  reportInteraction(
+    questionId: string,
+    interaction: import('../interaction.js').Interaction,
+    correct: boolean | null
+  ): void {
+    if (this.#mode !== 'normal') return;
+    super.reportInteraction(questionId, interaction, correct);
+  }
+
   setScore(score: number): void {
-    this.queue.enqueue(() =>
-      this.api.SetValue('cmi.score.raw', String(score))
+    if (this.#mode !== 'normal') return;
+    const raw = formatReal107(score);
+    // §4.2.4.3.5 — score.scaled is bounded to [-1, 1].
+    const scaled = formatReal107(Math.max(0, Math.min(1, score / 100)));
+    this.queue.enqueue(
+      () => this.api.SetValue('cmi.score.raw', raw),
+      'cmi.score.raw'
+    );
+    this.queue.enqueue(
+      () => this.api.SetValue('cmi.score.min', '0'),
+      'cmi.score.min'
     );
-    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.max', '100'),
+      'cmi.score.max'
+    );
+    this.queue.enqueue(
+      () => this.api.SetValue('cmi.score.scaled', scaled),
+      'cmi.score.scaled'
     );
   }
 
-  // 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 {
+    if (this.#mode !== 'normal') return;
     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),
+      'cmi.completion_status'
     );
+    // §4.2.4.2 — writing 1.0 surfaces a "100%" reading on LMS dashboards.
+    if (status === 'complete') {
+      this.queue.enqueue(
+        () => this.api.SetValue('cmi.progress_measure', '1'),
+        'cmi.progress_measure'
+      );
+    }
   }
 
   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));
+    if (this.#mode !== 'normal') return;
+    // Setting "unknown" explicitly prevents SCORM Cloud from rolling up
+    // a null status to "passed".
+    this.queue.enqueue(
+      () => this.api.SetValue('cmi.success_status', status),
+      'cmi.success_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));
+    if (this.#mode !== 'normal') return;
+    this.queue.enqueue(
+      () => this.api.SetValue('cmi.exit', mode),
+      'cmi.exit'
+    );
   }
 }

package/src/runtime/hooks.svelte.ts

@@ -1,4 +1,4 @@
-import { getContext, setContext, onDestroy } from 'svelte';
+import { getContext, setContext, onDestroy, onMount, tick } from 'svelte';
 import type { Interaction } from './interaction.js';
 import { isCorrect as isCorrectInteraction } from './interaction.js';
 import {
@@ -311,6 +311,20 @@ export function __warnUnsubmittedQuiz(stats: {
   );
 }
 
+/**
+ * Dev warning helper for a quiz host that mounts with no questions registered
+ * through useQuestion(). Such a page has a quiz wrapper but nothing the runtime
+ * can score or report to the LMS. Exported so tests can exercise the warning
+ * without depending on jsdom mount timing under vitest.
+ */
+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.'
+  );
+}
+
 /**
  * Programmatic quiz orchestration for custom quiz shells. Returns a handle
  * exposing the same state machine `<Quiz>` runs internally — register
@@ -585,6 +599,13 @@ export function useQuiz(opts: { element: () => HTMLElement | null }): UseQuizHan
     get isLockedCorrect() { return (i: number) => lockedCorrect.has(i); },
   });
 
+  onMount(() => {
+    if (!import.meta.env?.DEV) return;
+    // Questions register synchronously as child widgets initialise; a tick()
+    // also covers any effect-driven registration before we check.
+    void tick().then(() => __warnEmptyQuiz(questions.length));
+  });
+
   onDestroy(() => {
     __warnUnsubmittedQuiz({
       questionsCount: questions.length,