tessera-learn 0.2.3 → 0.4.0

package/src/runtime/adapters/discovery.ts

@@ -36,3 +36,14 @@ export function hasCMI5LaunchParams(): boolean {
     params.get('actor')
   );
 }
+
+/** Plain xAPI ("Tin Can") launch params on the URL. No fetch token required; `auth` is the Basic credential the LMS supplies in the launch link. */
+export function hasXAPILaunchParams(): boolean {
+  const params = new URLSearchParams(window.location.search);
+  return !!(
+    params.get('endpoint') &&
+    params.get('auth') &&
+    params.get('actor') &&
+    params.get('activity_id')
+  );
+}

package/src/runtime/adapters/index.ts

@@ -1,23 +1,25 @@
 import type { CourseConfig } from '../types.js';
+import type { Manifest } from '../../plugin/manifest.js';
 import type { PersistenceAdapter } from '../persistence.js';
 import { WebAdapter } from './web.js';
 import { SCORM12Adapter } from './scorm12.js';
 import { SCORM2004Adapter } from './scorm2004.js';
 import { CMI5Adapter } from './cmi5.js';
+import { XAPIAdapter } from './xapi.js';
 import {
   findSCORM12API,
   findSCORM2004API,
   hasCMI5LaunchParams,
+  hasXAPILaunchParams,
 } from './discovery.js';
+import {
+  LMSAdapterError,
+  lmsWarnLabel,
+  missingApiError,
+  type LMSStandard,
+} from './lms-error.js';
 
-export class LMSAdapterError extends Error {
-  standard: 'scorm12' | 'scorm2004' | 'cmi5';
-  constructor(standard: 'scorm12' | 'scorm2004' | 'cmi5', message: string) {
-    super(message);
-    this.name = 'LMSAdapterError';
-    this.standard = standard;
-  }
-}
+export { LMSAdapterError, missingApiError };
 
 export interface CreateAdapterOptions {
   /**
@@ -26,59 +28,24 @@ export interface CreateAdapterOptions {
    * so dev builds stay forgiving and production builds fail loud.
    */
   allowFallback?: boolean;
+  /** Course manifest — lets the WebAdapter fingerprint its page structure into the storage key. */
+  manifest?: Manifest;
 }
 
-type LMSStandard = 'scorm12' | 'scorm2004' | 'cmi5';
-
-/** Per-standard LMS wiring: `detect` returns an adapter when the LMS runtime is reachable, else null. Labels are the single source for the dev warning and production error. */
-const LMS_ADAPTERS: Record<
-  LMSStandard,
-  {
-    detect: () => PersistenceAdapter | null;
-    warnLabel: string;
-    name: string;
-    missingDetail: string;
-  }
-> = {
-  scorm12: {
-    detect: () => {
-      const api = findSCORM12API();
-      return api ? new SCORM12Adapter(api) : null;
-    },
-    warnLabel: 'SCORM 1.2 API',
-    name: 'SCORM 1.2',
-    missingDetail:
-      'No SCORM 1.2 API object found in the window.parent or window.opener chain.',
-  },
-  scorm2004: {
-    detect: () => {
-      const api = findSCORM2004API();
-      return api ? new SCORM2004Adapter(api) : null;
-    },
-    warnLabel: 'SCORM 2004 API',
-    name: 'SCORM 2004',
-    missingDetail:
-      'No SCORM 2004 API object found in the window.parent or window.opener chain.',
+/** Per-standard LMS wiring: `detect` returns an adapter when the LMS runtime is reachable, else null. Labels and the fail-loud error live in `./lms-error.js`. */
+const LMS_ADAPTERS: Record<LMSStandard, () => PersistenceAdapter | null> = {
+  scorm12: () => {
+    const api = findSCORM12API();
+    return api ? new SCORM12Adapter(api) : null;
   },
-  cmi5: {
-    detect: () => (hasCMI5LaunchParams() ? new CMI5Adapter() : null),
-    warnLabel: 'cmi5 launch parameters',
-    name: 'cmi5',
-    missingDetail:
-      'No cmi5 launch parameters (fetch / endpoint / activityId / actor) on the URL.',
+  scorm2004: () => {
+    const api = findSCORM2004API();
+    return api ? new SCORM2004Adapter(api) : null;
   },
+  cmi5: () => (hasCMI5LaunchParams() ? new CMI5Adapter() : null),
+  xapi: () => (hasXAPILaunchParams() ? new XAPIAdapter() : null),
 };
 
-function missingApiError(standard: LMSStandard): LMSAdapterError {
-  const { name, missingDetail } = LMS_ADAPTERS[standard];
-  return new LMSAdapterError(
-    standard,
-    `Tessera: this course is configured for ${name} but ${missingDetail} ` +
-      `The course must be launched from an LMS that provides the ${name} runtime. ` +
-      `If you are testing locally, run \`npm run dev\` instead, or set export.standard to "web".`,
-  );
-}
-
 /**
  * Select the appropriate persistence adapter based on course config.
  *
@@ -99,15 +66,15 @@ export function createAdapter(
   if (
     standard === 'scorm12' ||
     standard === 'scorm2004' ||
-    standard === 'cmi5'
+    standard === 'cmi5' ||
+    standard === 'xapi'
   ) {
-    const entry = LMS_ADAPTERS[standard];
-    const adapter = entry.detect();
+    const adapter = LMS_ADAPTERS[standard]();
     if (adapter) return adapter;
     if (!allowFallback) throw missingApiError(standard);
     console.warn(
-      `Tessera (dev): ${entry.warnLabel} not found — falling back to localStorage`,
+      `Tessera (dev): ${lmsWarnLabel(standard)} not found — falling back to localStorage`,
     );
   }
-  return new WebAdapter(config);
+  return new WebAdapter(config, options.manifest);
 }

package/src/runtime/adapters/lms-error.ts

@@ -0,0 +1,61 @@
+/**
+ * Per-standard LMS labels and the missing-API error, kept free of any adapter
+ * imports so both the runtime selector (`createAdapter`) and the build-time
+ * generated single-adapter modules can share one source of truth without
+ * pulling every adapter into a production bundle.
+ */
+
+export type LMSStandard = 'scorm12' | 'scorm2004' | 'cmi5' | 'xapi';
+
+export class LMSAdapterError extends Error {
+  standard: LMSStandard;
+  constructor(standard: LMSStandard, message: string) {
+    super(message);
+    this.name = 'LMSAdapterError';
+    this.standard = standard;
+  }
+}
+
+const STANDARD_INFO: Record<
+  LMSStandard,
+  { name: string; warnLabel: string; missingDetail: string }
+> = {
+  scorm12: {
+    name: 'SCORM 1.2',
+    warnLabel: 'SCORM 1.2 API',
+    missingDetail:
+      'No SCORM 1.2 API object found in the window.parent or window.opener chain.',
+  },
+  scorm2004: {
+    name: 'SCORM 2004',
+    warnLabel: 'SCORM 2004 API',
+    missingDetail:
+      'No SCORM 2004 API object found in the window.parent or window.opener chain.',
+  },
+  cmi5: {
+    name: 'cmi5',
+    warnLabel: 'cmi5 launch parameters',
+    missingDetail:
+      'No cmi5 launch parameters (fetch / endpoint / activityId / actor) on the URL.',
+  },
+  xapi: {
+    name: 'xAPI 1.0.3',
+    warnLabel: 'xAPI launch parameters',
+    missingDetail:
+      'No xAPI launch parameters (endpoint / auth / actor / activity_id) on the URL.',
+  },
+};
+
+export function lmsWarnLabel(standard: LMSStandard): string {
+  return STANDARD_INFO[standard].warnLabel;
+}
+
+export function missingApiError(standard: LMSStandard): LMSAdapterError {
+  const { name, missingDetail } = STANDARD_INFO[standard];
+  return new LMSAdapterError(
+    standard,
+    `Tessera: this course is configured for ${name} but ${missingDetail} ` +
+      `The course must be launched from an LMS that provides the ${name} runtime. ` +
+      `If you are testing locally, run \`npm run dev\` instead, or set export.standard to "web".`,
+  );
+}

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

@@ -74,7 +74,7 @@ export class SCORM2004Adapter extends BaseScormAdapter<SCORM2004API> {
     return this.#masteryScore;
   }
 
-  get #canWrite(): boolean {
+  protected canWrite(): boolean {
     return this.#mode === 'normal';
   }
 
@@ -97,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: import('../interaction.js').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

@@ -1,7 +1,9 @@
 import type { PersistenceAdapter, SavedState } from '../persistence.js';
 import type { CourseConfig } from '../types.js';
+import { courseIdentity } from '../types.js';
 import type { Interaction } from '../interaction.js';
-import { slugify } from '../slugify.js';
+import type { Manifest } from '../../plugin/manifest.js';
+import { structureFingerprint } from '../fingerprint.js';
 
 /**
  * Web persistence adapter — stores course state in localStorage.
@@ -11,9 +13,14 @@ 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}`;
+  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}` : ''}`;
   }
 
   async init(): Promise<void> {