tessera-learn 0.0.5 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tessera-learn",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "LMS tracking runtime for interactive learning content. One adapter layer (SCORM 1.2, SCORM 2004 4th Edition, cmi5, static Web), your choice of components.",
   "keywords": [
     "svelte",

package/src/plugin/export.ts

@@ -77,6 +77,8 @@ interface ScormManifestDialect {
   schemaversion: string;
   /** Attribute name on <resource>: SCORM 1.2 uses lowercase, 2004 uses camelCase. */
   scormTypeAttr: 'scormtype' | 'scormType';
+  /** Whitespace-separated namespace+XSD pairs for xsi:schemaLocation. */
+  schemaLocation: string;
 }
 
 const SCORM_DIALECTS: Record<'1.2' | '2004', ScormManifestDialect> = {
@@ -85,12 +87,19 @@ const SCORM_DIALECTS: Record<'1.2' | '2004', ScormManifestDialect> = {
     adlcpNs: 'http://www.adlnet.org/xsd/adlcp_rootv1p2',
     schemaversion: '1.2',
     scormTypeAttr: 'scormtype',
+    schemaLocation:
+      'http://www.imsproject.org/xsd/imscp_rootv1p1p2 imscp_rootv1p1p2.xsd ' +
+      'http://www.imsglobal.org/xsd/imsmd_rootv1p2p1 imsmd_rootv1p2p1.xsd ' +
+      'http://www.adlnet.org/xsd/adlcp_rootv1p2 adlcp_rootv1p2.xsd',
   },
   '2004': {
     rootNs: 'http://www.imsglobal.org/xsd/imscp_v1p1',
     adlcpNs: 'http://www.adlnet.org/xsd/adlcp_v1p3',
     schemaversion: '2004 4th Edition',
     scormTypeAttr: 'scormType',
+    schemaLocation:
+      'http://www.imsglobal.org/xsd/imscp_v1p1 imscp_v1p1.xsd ' +
+      'http://www.adlnet.org/xsd/adlcp_v1p3 adlcp_v1p3.xsd',
   },
 };
 
@@ -109,7 +118,9 @@ export function generateScormManifest(
   return `<?xml version="1.0" encoding="UTF-8"?>
 <manifest identifier="tessera-course" version="1.0"
   xmlns="${dialect.rootNs}"
-  xmlns:adlcp="${dialect.adlcpNs}">
+  xmlns:adlcp="${dialect.adlcpNs}"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="${dialect.schemaLocation}">
   <metadata>
     <schema>ADL SCORM</schema>
     <schemaversion>${dialect.schemaversion}</schemaversion>

package/src/runtime/adapters/retry.ts

@@ -1,13 +1,12 @@
 /**
- * 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".
+ * Surfaces LMSGetLastError / LMSGetErrorString / LMSGetDiagnostic so failure
+ * logs can name the cause instead of a generic "LMS call failed". SCORM
+ * Cloud uses the diagnostic to name the offending data-model element.
  */
 export interface LMSErrorReporter {
-  /** Last error from `LMSGetLastError` / `GetLastError`. */
   code(): string;
-  /** Human-readable message from `LMSGetErrorString` / `GetErrorString`. */
   message(code: string): string;
+  diagnostic?(code: string): string;
 }
 
 /** Default attempt count for LMS retry loops (one initial + two retries). */
@@ -33,19 +32,53 @@ function logRetryGiveUp(
   lastErrCode: string,
   context: string | undefined
 ): void {
-  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`
+    `Tessera: LMS call failed after retries${ctx}${formatLMSErrorDetail(errorReporter, lastErrCode)}, continuing without persistence`
   );
 }
 
+export function formatLMSErrorDetail(
+  errorReporter: LMSErrorReporter | undefined,
+  code: string
+): string {
+  if (!errorReporter || !code || code === '0') return '';
+  let msg = '';
+  let diag = '';
+  try { msg = errorReporter.message(code); } catch {}
+  try { diag = errorReporter.diagnostic?.(code) ?? ''; } catch {}
+  let detail = ` (LMS error ${code}`;
+  if (msg) detail += `: ${msg}`;
+  if (diag && diag !== msg) detail += ` — ${diag}`;
+  detail += ')';
+  return detail;
+}
+
+/** Sync call that warns with the LMS error code on failure (terminate-path). */
+export function callSyncOrWarn(
+  fn: () => any,
+  context: string,
+  errorReporter?: LMSErrorReporter
+): boolean {
+  let ok = false;
+  try {
+    ok = lmsCallSucceeded(fn());
+  } catch (err) {
+    console.warn(
+      `Tessera: LMS call threw [${context}] during terminate`,
+      err
+    );
+    return false;
+  }
+  if (!ok) {
+    const code = readLastErrorCode(errorReporter);
+    console.warn(
+      `Tessera: LMS call failed [${context}] during terminate${formatLMSErrorDetail(errorReporter, code)}`
+    );
+  }
+  return ok;
+}
+
 /**
  * Retry wrapper for LMS API calls.
  * Retries up to maxRetries times with exponential backoff.
@@ -68,17 +101,25 @@ export async function withRetry(
   context?: string
 ): Promise<boolean> {
   let lastErrCode = '';
+  let threw = false;
+  let lastError: unknown;
   for (let attempt = 0; attempt < maxRetries; attempt++) {
+    threw = false;
     try {
       if (lmsCallSucceeded(fn())) return true;
-    } catch {
-      // API call threw — treat as failure
+    } catch (err) {
+      threw = true;
+      lastError = err;
     }
     lastErrCode = readLastErrorCode(errorReporter);
     if (attempt < maxRetries - 1) {
       await new Promise((r) => setTimeout(r, backoffMs(attempt)));
     }
   }
+  if (threw) {
+    const ctx = context ? ` [${context}]` : '';
+    console.warn(`Tessera: LMS call threw${ctx} on final retry`, lastError);
+  }
   logRetryGiveUp(errorReporter, lastErrCode, context);
   return false;
 }
@@ -275,6 +316,36 @@ export function formatHHMMSS(totalSeconds: number): string {
   return `${hh}:${mm}:${ss}.00`;
 }
 
+/**
+ * SCORM 2004 4E §4.2/§4.3 define CMIDecimal-like elements as real(10,7) —
+ * `String(1/3)` exceeds that and trips SCORM Cloud with error 406. Rounds,
+ * then trims trailing zeros (no padded "0.8500000" forms).
+ */
+export function formatReal107(value: number): string {
+  if (!Number.isFinite(value)) return '0';
+  const rounded = Math.round(value * 1e7) / 1e7;
+  return rounded
+    .toFixed(7)
+    .replace(/(\.\d*?)0+$/, '$1')
+    .replace(/\.$/, '');
+}
+
+/**
+ * SCORM 2004 4E §3.3.10.1 references ISO 8601 §5.3.3 — local date+time, no
+ * zone designator. Strict validators reject `Z`, `±hh:mm`, and fractional
+ * seconds with error 406. UTC components are used so writes don't drift
+ * across local-TZ flips even though the format is zone-free.
+ */
+export function formatISO8601Timestamp(date: Date): string {
+  const yyyy = date.getUTCFullYear();
+  const mm = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(date.getUTCDate()).padStart(2, '0');
+  const hh = String(date.getUTCHours()).padStart(2, '0');
+  const mi = String(date.getUTCMinutes()).padStart(2, '0');
+  const ss = String(date.getUTCSeconds()).padStart(2, '0');
+  return `${yyyy}-${mm}-${dd}T${hh}:${mi}:${ss}`;
+}
+
 /**
  * Format seconds as ISO 8601 duration: PT1H30M45S
  */

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'
+    );
   }
 }