tessera-learn 0.0.5 → 0.0.6

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/interaction-format.ts

@@ -1,79 +1,125 @@
 /**
- * Format `Interaction` payloads for SCORM 2004 / xAPI `cmi.interactions.n.*`
- * writes. Delimiters follow SCORM 2004 4th Edition RTE §4.2.7 — `cmi5` (xAPI)
- * reuses the same encoding for `cmi.interaction` activity statements.
- *
- *   ITEM delimiter   [,]
- *   PAIR delimiter   [.]
- *   RANGE delimiter  [:]
+ * SCORM 1.2 RTE §3.4.7 vs SCORM 2004 4E RTE §4.2.7 differ in delimiter
+ * encoding and identifier rules; cmi5 (xAPI) reuses the 2004 encoding.
  */
 
 import type { Interaction } from './interaction.js';
 
+export interface InteractionFormat {
+  itemDelim: string;
+  pairDelim: string;
+  rangeDelim: string;
+  /**
+   * SCORM 1.2 has no numeric range syntax — `correct_responses.n.pattern`
+   * is a single CMIDecimal. SCORM 2004 supports `min[:]max`.
+   */
+  supportsNumericRange: boolean;
+  formatBoolean(value: boolean): string;
+  identifier(value: string): string;
+}
+
+export const SCORM12_INTERACTION_FORMAT: InteractionFormat = {
+  itemDelim: ',',
+  pairDelim: '.',
+  rangeDelim: ':',
+  supportsNumericRange: false,
+  formatBoolean: (v) => (v ? 't' : 'f'),
+  identifier: shortIdentifier,
+};
+
+/**
+ * Bracketed delimiters are literal text, not regex. xAPI parses them the
+ * same way.
+ */
+export const SCORM2004_INTERACTION_FORMAT: InteractionFormat = {
+  itemDelim: '[,]',
+  pairDelim: '[.]',
+  rangeDelim: '[:]',
+  supportsNumericRange: true,
+  formatBoolean: (v) => (v ? 'true' : 'false'),
+  identifier: shortIdentifier,
+};
+
 /**
- * Serialize the learner response to the `learner_response` / `student_response`
- * field format expected by SCORM 2004 and mirrored by xAPI.
+ * SCORM `short_identifier_type` / `CMIIdentifier`: alphanumerics +
+ * underscore, max 250 chars. Strict validators (SCORM Cloud) reject raw
+ * option labels with spaces or punctuation with error 405/406.
  */
-export function formatResponse(i: Interaction): string {
+function shortIdentifier(value: string): string {
+  const cleaned = value.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  const trimmed = cleaned.slice(0, 250);
+  return trimmed || '_';
+}
+
+export function formatResponse(
+  i: Interaction,
+  fmt: InteractionFormat = SCORM2004_INTERACTION_FORMAT
+): string {
   switch (i.type) {
     case 'choice':
     case 'sequencing':
-      return i.response.join('[,]');
+      return i.response.map(fmt.identifier).join(fmt.itemDelim);
     case 'true-false':
-      return i.response ? 'true' : 'false';
+      return fmt.formatBoolean(i.response);
     case 'fill-in':
     case 'long-fill-in':
     case 'likert':
     case 'other':
       return i.response;
     case 'matching':
-      return i.response.map(([l, r]) => `${l}[.]${r}`).join('[,]');
+      return i.response
+        .map(([l, r]) => `${fmt.identifier(l)}${fmt.pairDelim}${fmt.identifier(r)}`)
+        .join(fmt.itemDelim);
     case 'numeric':
       return String(i.response);
     case 'performance':
-      return i.response.map(([s, v]) => `${s}[.]${v}`).join('[,]');
+      return i.response
+        .map(([s, v]) => `${fmt.identifier(s)}${fmt.pairDelim}${fmt.identifier(String(v))}`)
+        .join(fmt.itemDelim);
   }
 }
 
-/**
- * Serialize the `correct_responses.0.pattern` for this interaction. Returns
- * `null` if no correct pattern was provided.
- */
-export function formatCorrectPattern(i: Interaction): string | null {
+/** Returns null when no correct pattern was provided. */
+export function formatCorrectPattern(
+  i: Interaction,
+  fmt: InteractionFormat = SCORM2004_INTERACTION_FORMAT
+): string | null {
   if (i.correct === undefined) return null;
   switch (i.type) {
     case 'choice':
     case 'sequencing':
-      return (i.correct as string[]).join('[,]');
+      return (i.correct as string[]).map(fmt.identifier).join(fmt.itemDelim);
     case 'true-false':
-      return (i.correct as boolean) ? 'true' : 'false';
+      return fmt.formatBoolean(i.correct as boolean);
     case 'fill-in':
     case 'long-fill-in':
-      // SCORM 2004 accepts multiple acceptable patterns joined with `[,]`.
-      return (i.correct as string[]).join('[,]');
+      return (i.correct as string[]).join(fmt.itemDelim);
     case 'matching':
-      return (i.correct as Array<[string, string]>).map(([l, r]) => `${l}[.]${r}`).join('[,]');
+      return (i.correct as Array<[string, string]>)
+        .map(([l, r]) => `${fmt.identifier(l)}${fmt.pairDelim}${fmt.identifier(r)}`)
+        .join(fmt.itemDelim);
     case 'numeric': {
       const c = i.correct as { min?: number; max?: number };
-      const min = c.min ?? '';
-      const max = c.max ?? '';
-      return `${min}[:]${max}`;
+      if (c.min !== undefined && c.max !== undefined && c.min === c.max) {
+        return String(c.min);
+      }
+      if (c.min !== undefined && c.max === undefined) return String(c.min);
+      if (c.min === undefined && c.max !== undefined) return String(c.max);
+      // True range — drop the pattern in 1.2 (rely on `result` for pass/fail).
+      if (!fmt.supportsNumericRange) return null;
+      return `${c.min ?? ''}${fmt.rangeDelim}${c.max ?? ''}`;
     }
     case 'likert':
     case 'other':
       return i.correct as string;
     case 'performance':
       return (i.correct as Array<[string, string | number]>)
-        .map(([s, v]) => `${s}[.]${v}`)
-        .join('[,]');
+        .map(([s, v]) => `${fmt.identifier(s)}${fmt.pairDelim}${fmt.identifier(String(v))}`)
+        .join(fmt.itemDelim);
   }
 }
 
-/**
- * Map Tessera interaction types to SCORM 1.2's narrower vocabulary. SCORM 1.2
- * does not define `long-fill-in`; fall back to `fill-in`. `other` is not in
- * the spec either — fall back to `fill-in` (free text).
- */
+/** SCORM 1.2 has no `long-fill-in` or `other` — both fall back to `fill-in`. */
 export function scorm12Type(type: Interaction['type']): string {
   switch (type) {
     case 'long-fill-in':
@@ -85,26 +131,15 @@ export function scorm12Type(type: Interaction['type']): string {
   }
 }
 
-/**
- * Per-standard differences in how `cmi.interactions.n.*` is written. The
- * SCORM 1.2 vs 2004 deltas are: response field name, result vocabulary,
- * timestamp field name+format, and the type vocabulary mapping.
- */
 export interface ScormInteractionSpec {
   responseField: 'student_response' | 'learner_response';
   timestampField: 'time' | 'timestamp';
-  /** Wall-clock value formatted to whichever style the standard expects. */
   timestamp: string;
-  /** Mapped interaction type — already narrowed for SCORM 1.2 callers. */
   typeValue: string;
   resultLabels: { correct: string; incorrect: string };
+  format: InteractionFormat;
 }
 
-/**
- * Build the ordered list of `cmi.interactions.n.*` writes that SCORM 1.2 and
- * SCORM 2004 adapters share. Caller wires each pair through its own LMS
- * SetValue queue (the queueing semantics differ between adapters).
- */
 export function buildScormInteractionFields(
   prefix: string,
   questionId: string,
@@ -115,9 +150,9 @@ export function buildScormInteractionFields(
   const fields: Array<[string, string]> = [
     [`${prefix}.id`, questionId],
     [`${prefix}.type`, spec.typeValue],
-    [`${prefix}.${spec.responseField}`, formatResponse(interaction)],
+    [`${prefix}.${spec.responseField}`, formatResponse(interaction, spec.format)],
   ];
-  const pattern = formatCorrectPattern(interaction);
+  const pattern = formatCorrectPattern(interaction, spec.format);
   if (pattern !== null) {
     fields.push([`${prefix}.correct_responses.0.pattern`, pattern]);
   }