tessera-learn 0.3.0 → 0.4.0

package/src/runtime/App.svelte

@@ -14,6 +14,7 @@
   import { applyBranding } from './branding.js';
   import { DurationTracker } from './duration.js';
   import { createAdapter } from 'virtual:tessera-adapter';
+  import { structureFingerprint, shouldRestore } from './fingerprint.js';
   import { buildXAPIClient } from 'virtual:tessera-xapi-setup';
   import { registerXAPIClient } from './xapi/registry.js';
   import {
@@ -25,6 +26,7 @@
 
   // ---- Persistence ----
   const adapter = createAdapter(config, { manifest });
+  const currentFingerprint = structureFingerprint(manifest);
   let persistenceReady = $state(false);
   // Holds the resolved xAPI client for unload-time markUnloading. Set
   // after adapter.init() resolves and registered globally so useXAPI()
@@ -206,6 +208,7 @@
     }
     return {
       b: nav.currentPageIndex,
+      f: currentFingerprint,
       v: [...progress.visitedPages],
       q,
       d: duration.totalSeconds,
@@ -403,7 +406,7 @@
     }
 
     const saved = adapter.getState();
-    if (saved) {
+    if (saved && shouldRestore(saved, currentFingerprint, config.resume)) {
       restoreState(saved);
       prevCompletionStatus = progress.completionStatus;
       prevSuccessStatus = progress.successStatus;

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

@@ -66,6 +66,16 @@ export abstract class BaseScormAdapter<TApi> implements PersistenceAdapter {
     return this.api;
   }
 
+  // SCORM 2004 overrides this to block writes in browse/review mode (§4.2.1.5).
+  protected canWrite(): boolean {
+    return true;
+  }
+
+  protected set(key: string, value: string): void {
+    if (!this.canWrite()) return;
+    this.queue.enqueue(() => this.dialect.setValue(this.api, key, value), key);
+  }
+
   async init(): Promise<void> {
     const initialized = await withRetry(
       () => this.dialect.initialize(this.api),
@@ -129,6 +139,7 @@ export abstract class BaseScormAdapter<TApi> implements PersistenceAdapter {
   }
 
   saveState(state: SavedState): void {
+    if (!this.canWrite()) return;
     this.#state = state;
     const json = JSON.stringify(state);
     if (
@@ -144,19 +155,11 @@ export abstract class BaseScormAdapter<TApi> implements PersistenceAdapter {
           `larger-limit standard (scorm2004/cmi5).`,
       );
     }
-    this.queue.enqueue(
-      () => this.dialect.setValue(this.api, 'cmi.suspend_data', json),
-      'cmi.suspend_data',
-    );
+    this.set('cmi.suspend_data', json);
   }
 
   setDuration(seconds: number): void {
-    const formatted = this.dialect.formatDuration(seconds);
-    this.queue.enqueue(
-      () =>
-        this.dialect.setValue(this.api, this.dialect.sessionTimeKey, formatted),
-      this.dialect.sessionTimeKey,
-    );
+    this.set(this.dialect.sessionTimeKey, this.dialect.formatDuration(seconds));
   }
 
   reportInteraction(
@@ -164,6 +167,7 @@ export abstract class BaseScormAdapter<TApi> implements PersistenceAdapter {
     interaction: Interaction,
     correct: boolean | null,
   ): void {
+    if (!this.canWrite()) return;
     const n = this.interactionCount++;
     const fields = buildScormInteractionFields(
       `cmi.interactions.${n}`,
@@ -180,10 +184,7 @@ export abstract class BaseScormAdapter<TApi> implements PersistenceAdapter {
       },
     );
     for (const [key, value] of fields) {
-      this.queue.enqueue(
-        () => this.dialect.setValue(this.api, key, value),
-        key,
-      );
+      this.set(key, value);
     }
   }
 

package/src/runtime/adapters/scorm12.ts

@@ -66,25 +66,13 @@ export class SCORM12Adapter extends BaseScormAdapter<SCORM12API> {
   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',
-    );
+    this.set('cmi.core.lesson_location', String(state.b));
   }
 
   setScore(score: number): void {
-    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.set('cmi.core.score.raw', formatReal107(score));
+    this.set('cmi.core.score.min', '0');
+    this.set('cmi.core.score.max', '100');
   }
 
   setCompletionStatus(status: 'incomplete' | 'complete'): void {
@@ -101,18 +89,11 @@ export class SCORM12Adapter extends BaseScormAdapter<SCORM12API> {
 
   #flushLessonStatus(): void {
     const value = this.#successStatus ?? this.#completionStatus;
-    this.queue.enqueue(
-      () => this.api.LMSSetValue('cmi.core.lesson_status', value),
-      'cmi.core.lesson_status',
-    );
+    this.set('cmi.core.lesson_status', value);
   }
 
   setExit(mode: 'suspend' | 'normal'): void {
     // SCORM 1.2 §4.2.2 vocabulary: time-out, suspend, logout, "" (normal).
-    const value = mode === 'suspend' ? 'suspend' : '';
-    this.queue.enqueue(
-      () => this.api.LMSSetValue('cmi.core.exit', value),
-      'cmi.core.exit',
-    );
+    this.set('cmi.core.exit', mode === 'suspend' ? 'suspend' : '');
   }
 }

package/src/runtime/adapters/scorm2004.ts

@@ -1,5 +1,4 @@
 import { SCORM2004_INTERACTION_FORMAT } from '../interaction-format.js';
-import type { Interaction } from '../interaction.js';
 import type { SavedState } from '../persistence.js';
 import { BaseScormAdapter, type ScormDialect } from './scorm-base.js';
 import {
@@ -75,7 +74,7 @@ export class SCORM2004Adapter extends BaseScormAdapter<SCORM2004API> {
     return this.#masteryScore;
   }
 
-  get #canWrite(): boolean {
+  protected canWrite(): boolean {
     return this.#mode === 'normal';
   }
 
@@ -98,80 +97,38 @@ export class SCORM2004Adapter extends BaseScormAdapter<SCORM2004API> {
   }
 
   saveState(state: SavedState): void {
-    if (!this.#canWrite) 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.#canWrite) return;
-    super.setDuration(seconds);
-  }
-
-  reportInteraction(
-    questionId: string,
-    interaction: Interaction,
-    correct: boolean | null,
-  ): void {
-    if (!this.#canWrite) return;
-    super.reportInteraction(questionId, interaction, correct);
+    this.set('cmi.location', String(state.b));
   }
 
   setScore(score: number): void {
-    if (!this.#canWrite) return;
-    const raw = formatReal107(score);
+    this.set('cmi.score.raw', formatReal107(score));
+    this.set('cmi.score.min', '0');
+    this.set('cmi.score.max', '100');
     // §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.max', '100'),
-      'cmi.score.max',
-    );
-    this.queue.enqueue(
-      () => this.api.SetValue('cmi.score.scaled', scaled),
+    this.set(
       'cmi.score.scaled',
+      formatReal107(Math.max(0, Math.min(1, score / 100))),
     );
   }
 
   setCompletionStatus(status: 'incomplete' | 'complete'): void {
-    if (!this.#canWrite) return;
-    const value = status === 'complete' ? 'completed' : 'incomplete';
-    this.queue.enqueue(
-      () => this.api.SetValue('cmi.completion_status', value),
+    this.set(
       'cmi.completion_status',
+      status === 'complete' ? 'completed' : 'incomplete',
     );
     // §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',
-      );
-    }
+    if (status === 'complete') this.set('cmi.progress_measure', '1');
   }
 
   setSuccessStatus(status: 'passed' | 'failed' | 'unknown'): void {
-    if (!this.#canWrite) 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',
-    );
+    this.set('cmi.success_status', status);
   }
 
   setExit(mode: 'suspend' | 'normal'): void {
-    if (!this.#canWrite) return;
-    this.queue.enqueue(() => this.api.SetValue('cmi.exit', mode), 'cmi.exit');
+    this.set('cmi.exit', mode);
   }
 }

package/src/runtime/adapters/web.ts

@@ -3,19 +3,7 @@ import type { CourseConfig } from '../types.js';
 import { courseIdentity } from '../types.js';
 import type { Interaction } from '../interaction.js';
 import type { Manifest } from '../../plugin/manifest.js';
-
-// FNV-1a over the ordered page slugs. SavedState is keyed by page index, so a
-// structure change must change the key — else stale state restores onto the
-// wrong pages. Slugs can't contain a NUL, so it's a collision-proof delimiter.
-function structureFingerprint(manifest: Manifest): string {
-  const slugs = manifest.pages.map((p) => p.slug).join('\0');
-  let h = 0x811c9dc5;
-  for (let i = 0; i < slugs.length; i++) {
-    h ^= slugs.charCodeAt(i);
-    h = Math.imul(h, 0x01000193);
-  }
-  return (h >>> 0).toString(36);
-}
+import { structureFingerprint } from '../fingerprint.js';
 
 /**
  * Web persistence adapter — stores course state in localStorage.
@@ -27,6 +15,10 @@ export class WebAdapter implements PersistenceAdapter {
 
   constructor(config: CourseConfig, manifest?: Manifest) {
     const base = courseIdentity(config) || 'tessera-course';
+    // Fingerprint in the key invalidates web resume on a structure change (a
+    // changed key misses, so getState() returns null). LMS adapters can't key
+    // their storage, so they rely on SavedState.f + shouldRestore instead. Keep
+    // both — neither mechanism covers the other's adapters.
     const fp = manifest ? structureFingerprint(manifest) : '';
     this.#storageKey = `tessera-${base}${fp ? `-${fp}` : ''}`;
   }

package/src/runtime/fingerprint.ts

@@ -0,0 +1,28 @@
+import type { Manifest } from '../plugin/manifest.js';
+import type { SavedState } from './persistence.js';
+
+// FNV-1a over the ordered page slugs. SavedState is keyed by page index, so a
+// structure change must change the fingerprint — else stale state restores onto
+// the wrong pages. Slugs can't contain a NUL, so it's a collision-proof delimiter.
+export function structureFingerprint(manifest: Manifest): string {
+  const slugs = manifest.pages.map((p) => p.slug).join('\0');
+  let h = 0x811c9dc5;
+  for (let i = 0; i < slugs.length; i++) {
+    h ^= slugs.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(36);
+}
+
+// `never` always starts fresh; otherwise a saved fingerprint that no longer
+// matches the current structure is discarded. State saved before fingerprinting
+// (no `f`) is trusted so upgrading the runtime never wipes an in-progress learner.
+export function shouldRestore(
+  saved: SavedState,
+  currentFingerprint: string,
+  resume: 'auto' | 'never' = 'auto',
+): boolean {
+  if (resume === 'never') return false;
+  if (saved.f !== undefined && saved.f !== currentFingerprint) return false;
+  return true;
+}

package/src/runtime/interaction-format.ts

@@ -165,7 +165,6 @@ export function formatCorrectPattern(
 export function scorm12Type(type: Interaction['type']): string {
   switch (type) {
     case 'long-fill-in':
-      return 'fill-in';
     case 'other':
       return 'fill-in';
     default:

package/src/runtime/persistence.ts

@@ -60,4 +60,8 @@ export interface SavedState {
   gs?: number[];
   /** Manual completion latch. 1 if the learner triggered manual completion. Absent otherwise. */
   m?: 1;
+  /** Structure fingerprint (FNV-1a over ordered page slugs) at save time.
+   * On resume, a mismatch discards the blob — the course structure changed.
+   * Absent on state saved before fingerprinting; treated as a match. */
+  f?: string;
 }

package/src/runtime/types.ts

@@ -40,6 +40,9 @@ export interface CourseConfig {
   description?: string;
   author?: string;
   version?: string;
+  /** Resume policy. 'auto' (default) restores saved progress unless the page
+   * structure changed since it was saved; 'never' always starts fresh. */
+  resume?: 'auto' | 'never';
   /** BCP-47 language tag for <html lang>. Defaults to 'en'. WCAG 3.1.1. */
   language?: string;
   /** Accessibility checker configuration. */

package/src/runtime/xapi/publisher.ts

@@ -494,17 +494,21 @@ export class XAPIPublisher {
     return headers;
   }
 
-  #fetchWithToken(
-    token: string,
-    body: string,
-    keepalive: boolean,
-  ): Promise<SendOutcome> {
+  #post(token: string, body: string, keepalive: boolean): Promise<Response> {
     return fetch(this.#statementsUrl, {
       method: 'POST',
       headers: this.#buildHeaders(token),
       body,
       keepalive,
-    })
+    });
+  }
+
+  #fetchWithToken(
+    token: string,
+    body: string,
+    keepalive: boolean,
+  ): Promise<SendOutcome> {
+    return this.#post(token, body, keepalive)
       .then((resp) => this.#handleResponse(resp, body, keepalive))
       .catch((err) => ({
         ok: false,
@@ -529,14 +533,7 @@ export class XAPIPublisher {
     ) {
       this.#cachedAuth = null;
       return this.#resolveAuth(true)
-        .then((newToken) =>
-          fetch(this.#statementsUrl, {
-            method: 'POST',
-            headers: this.#buildHeaders(newToken),
-            body,
-            keepalive,
-          }),
-        )
+        .then((newToken) => this.#post(newToken, body, keepalive))
         .then((retryResp): SendOutcome => {
           if (retryResp.ok || retryResp.status === 409) {
             return { ok: true, status: retryResp.status };