refactor: dedupe SCORM writes and xAPI publisher fetch

- Add a gated `set()` helper + `canWrite()` hook on BaseScormAdapter so the
  SCORM 1.2/2004 adapters stop repeating `queue.enqueue(() => SetValue...)`,
  and SCORM 2004 expresses its browse/review write-gating once instead of in
  seven methods.
- Collapse the duplicate `scorm12Type` cases.
- Extract a single `#post()` in XAPIPublisher so the 401-retry path no longer
  rebuilds the statements POST.
- Drop a redundant `isCorrectOption` call in MultipleChoice.

Behavior-preserving; full unit suite (976 tests) green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: redmodd

.changeset/scorm-write-helper.md

@@ -0,0 +1,6 @@
+---
+'tessera-learn': patch
+'create-tessera': patch
+---
+
+Internal refactor of the SCORM adapters and xAPI publisher; no behavior change.

packages/tessera-learn/src/components/MultipleChoice.svelte

@@ -62,8 +62,7 @@
   function getOptionClass(optIndex) {
     if (!q.feedbackVisible) return '';
     if (isCorrectOption(optIndex)) return 'correct';
-    if (optIndex === selectedOption && !isCorrectOption(optIndex))
-      return 'incorrect';
+    if (optIndex === selectedOption) return 'incorrect';
     return '';
   }
 </script>

packages/tessera-learn/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,26 +155,19 @@ 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(
     questionId: string,
     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);
     }
   }
 

packages/tessera-learn/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' : '');
   }
 }

packages/tessera-learn/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);
   }
 }

packages/tessera-learn/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:

packages/tessera-learn/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 };