tessera-learn 0.0.8 → 0.0.9

package/src/components/Sorting.svelte

@@ -1,5 +1,5 @@
 <script>
-  import { getContext, onMount } from 'svelte';
+  import { onMount } from 'svelte';
   import { SvelteMap } from 'svelte/reactivity';
   import { useQuestion } from '../runtime/hooks.svelte.js';
   import { slugFromQuestion, shuffle } from './util.js';
@@ -19,9 +19,6 @@
     weight = 1,
   } = $props();
 
-  const quiz = getContext('tessera-quiz');
-  const standalone = !quiz;
-
   let queue = $state([]);              // item indices not yet placed; queue[0] is current
   let placements = $state(new SvelteMap()); // itemIdx → targetIdx
   let dragOver = $state(null);         // target index highlighted during drag
@@ -36,15 +33,6 @@
     isDragging = false;
   }
 
-  if (standalone) {
-    initQueue();
-  } else {
-    onMount(() => {
-      initQueue();
-      quiz.setRender(myIndex, renderQuestion);
-    });
-  }
-
   function checkAnswer(answer) {
     if (!answer || !(answer instanceof Map)) return false;
     if (answer.size !== items.length) return false;
@@ -61,7 +49,7 @@
   // Sorting is semantically a categorization (each item → one target) and maps
   // cleanly to SCORM 2004's `matching` interaction. We emit [itemIdx, targetIdx]
   // pairs as stringified ids.
-  const handle = useQuestion({
+  const q = useQuestion({
     get id() { return id ?? `sorting-${slugFromQuestion(question)}`; },
     get weight() { return weight; },
     get maxRetries() { return maxRetries; },
@@ -73,13 +61,20 @@
     reset: resetState,
   });
 
-  const myIndex = $derived(handle.quizIndex ?? -1);
+  // `q.mode` is fixed for the lifetime of the widget; capture it once so
+  // setup-time branches don't trip Svelte's "state_referenced_locally" warning.
+  const inQuiz = q.mode === 'quiz';
 
-  let currentItemIdx = $derived(queue.length > 0 ? queue[0] : null);
+  if (!inQuiz) {
+    initQueue();
+  } else {
+    onMount(() => {
+      initQueue();
+      q.setRender(renderQuestion);
+    });
+  }
 
-  let isLocked = $derived(standalone ? false : quiz.isLockedCorrect(myIndex));
-  let isDisabled = $derived(standalone ? handle.submitted : quiz.isAnswerLocked(myIndex));
-  let showFeedback = $derived(standalone ? handle.submitted : quiz.feedbackVisible(myIndex));
+  let currentItemIdx = $derived(queue.length > 0 ? queue[0] : null);
 
   function getItemsForTarget(targetIdx) {
     const result = [];
@@ -94,19 +89,22 @@
   }
 
   function placeCard(targetIdx) {
-    if (isDisabled || currentItemIdx === null) return;
+    if (q.locked || currentItemIdx === null) return;
     const itemIdx = queue[0];
     placements.set(itemIdx, targetIdx);
     queue = queue.slice(1);
     cardSelected = false;
-    if (!standalone) quiz.setAnswer(myIndex, new Map(placements));
+    if (inQuiz) {
+      q.setAnswer(new Map(placements));
+      if (placements.size === items.length) q.commit();
+    }
   }
 
   function returnCard(itemIdx) {
-    if (isDisabled) return;
+    if (q.locked) return;
     placements.delete(itemIdx);
     queue = [itemIdx, ...queue];
-    if (!standalone) quiz.setAnswer(myIndex, new Map(placements));
+    if (inQuiz) q.setAnswer(new Map(placements));
   }
 
   // --- Drag handlers ---
@@ -122,7 +120,7 @@
   }
 
   function onDragOver(e, targetIdx) {
-    if (isDisabled) return;
+    if (q.locked) return;
     e.preventDefault();
     e.dataTransfer.dropEffect = 'move';
     dragOver = targetIdx;
@@ -145,7 +143,7 @@
   // --- Click / tap handlers ---
 
   function onCardClick() {
-    if (isDisabled || currentItemIdx === null) return;
+    if (q.locked || currentItemIdx === null) return;
     cardSelected = !cardSelected;
   }
 
@@ -157,7 +155,7 @@
   }
 
   function onTargetClick(targetIdx) {
-    if (isDisabled || !cardSelected) return;
+    if (q.locked || !cardSelected) return;
     placeCard(targetIdx);
   }
 
@@ -174,7 +172,7 @@
   <p class="tessera-sorting-question">{question}</p>
 
   <!-- Card deck: shows the current card to be placed -->
-  {#if !isDisabled}
+  {#if !q.locked}
     <div class="tessera-sorting-deck" aria-live="polite" aria-atomic="false">
       {#if currentItemIdx !== null}
         <div class="tessera-sorting-deck-inner">
@@ -212,17 +210,17 @@
   {/if}
 
   <!-- Drop targets -->
-  <div class="tessera-sorting-targets" class:targets-active={cardSelected && !isDisabled}>
+  <div class="tessera-sorting-targets" class:targets-active={cardSelected && !q.locked}>
     {#each targets as targetLabel, targetIdx}
       {@const targetItems = getItemsForTarget(targetIdx)}
       <div
         class="tessera-sorting-target"
         class:drag-over={dragOver === targetIdx}
-        class:clickable={cardSelected && !isDisabled}
+        class:clickable={cardSelected && !q.locked}
         role="button"
         tabindex="0"
-        aria-disabled={!(cardSelected && !isDisabled)}
-        aria-label="Target: {targetLabel}{cardSelected && !isDisabled ? ` (activate to place ${items[currentItemIdx]})` : ''}"
+        aria-disabled={!(cardSelected && !q.locked)}
+        aria-label="Target: {targetLabel}{cardSelected && !q.locked ? ` (activate to place ${items[currentItemIdx]})` : ''}"
         ondragover={(e) => onDragOver(e, targetIdx)}
         ondragleave={onDragLeave}
         ondrop={(e) => onDrop(e, targetIdx)}
@@ -235,17 +233,17 @@
             {#each targetItems as itemIdx}
               <div
                 class="tessera-sorting-placed-item"
-                class:correct={showFeedback && isCorrectPlacement(itemIdx)}
-                class:incorrect={showFeedback && !isCorrectPlacement(itemIdx)}
+                class:correct={q.feedbackVisible && isCorrectPlacement(itemIdx)}
+                class:incorrect={q.feedbackVisible && !isCorrectPlacement(itemIdx)}
               >
                 <span class="tessera-sorting-item-text">{items[itemIdx]}</span>
-                {#if !isDisabled}
+                {#if !q.locked}
                   <button
                     class="tessera-sorting-remove"
                     aria-label="Return '{items[itemIdx]}' to deck"
                     onclick={(e) => { e.stopPropagation(); returnCard(itemIdx); }}
                   >×</button>
-                {:else if showFeedback}
+                {:else if q.feedbackVisible}
                   <span class="tessera-sorting-item-icon" aria-hidden="true">
                     {isCorrectPlacement(itemIdx) ? '✓' : '✗'}
                   </span>
@@ -259,7 +257,7 @@
   </div>
 
   <!-- Feedback (shown after standalone submit or quiz feedbackVisible) -->
-  {#if showFeedback}
+  {#if q.feedbackVisible}
     {@const isCorrect = checkAnswer(placements)}
     <div class="tessera-sorting-review">
       {#if isCorrect}
@@ -285,23 +283,23 @@
           <p class="tessera-sorting-feedback incorrect">{incorrectFeedback}</p>
         {/if}
       {/if}
-      {#if standalone && handle.canRetry}
-        <RetryButton onclick={() => handle.retry()} />
+      {#if !inQuiz && q.canRetry}
+        <RetryButton onclick={() => q.retry()} />
       {/if}
     </div>
   {/if}
 
   <!-- Standalone Check button (shown once all cards are placed) -->
-  {#if standalone && !handle.submitted && placements.size === items.length}
+  {#if !inQuiz && !q.submitted && placements.size === items.length}
     <div class="tessera-sorting-actions">
-      <button class="tessera-btn-primary tessera-sorting-check" onclick={() => handle.submit()}>
+      <button class="tessera-btn-primary tessera-sorting-check" onclick={() => q.submit()}>
         Check Answer
       </button>
     </div>
   {/if}
 {/snippet}
 
-{#if standalone}
+{#if !inQuiz}
   <div class="tessera-sorting" aria-label={question}>
     {@render sortingContent()}
   </div>
@@ -309,7 +307,7 @@
 
 {#snippet renderQuestion()}
   <div class="tessera-sorting" aria-label={question}>
-    {#if isLocked}
+    {#if q.isLockedCorrect}
       <LockedBanner />
     {/if}
     {@render sortingContent()}

package/src/index.ts

@@ -48,6 +48,7 @@ export type {
   UseQuestionOptions,
   UseQuestionHandle,
   UseQuizHandle,
+  Question,
 } from './runtime/hooks.svelte.js';
 export type {
   XAPIConfig,

package/src/plugin/index.ts

@@ -207,6 +207,11 @@ function tesseraConfigPlugin(): Plugin {
             '$assets': resolve(root, 'assets'),
           },
         },
+        // tessera-learn ships .ts/.svelte.ts source; Vite's dep optimizer
+        // doesn't run vite-plugin-svelte's preprocessor, so skip pre-bundling.
+        optimizeDeps: {
+          exclude: ['tessera-learn'],
+        },
       };
     },
 

package/src/plugin/validation.ts

@@ -542,7 +542,8 @@ function validatePageFile(
   if (
     pageConfig?.quiz &&
     !HAS_USE_QUESTION_RE.test(content) &&
-    !HAS_QUESTION_TAG_RE.test(content)
+    !HAS_QUESTION_TAG_RE.test(content) &&
+    !HAS_LOCAL_SVELTE_IMPORT_RE.test(content)
   ) {
     warnings.push(
       `${fileRel}: quiz page has no question components or useQuestion() calls — ` +
@@ -810,7 +811,7 @@ function validateQuizConfig(quiz: unknown, fileRel: string, errors: string[]): v
     }
   }
 
-  for (const field of ['graded', 'gatesProgress', 'showFeedback']) {
+  for (const field of ['graded', 'gatesProgress']) {
     if (cfg[field] !== undefined && typeof cfg[field] !== 'boolean') {
       errors.push(
         `${fileRel}: quiz.${field} must be a boolean, got ${typeof cfg[field]}`
@@ -1041,6 +1042,10 @@ const HAS_USE_QUESTION_RE = /\buseQuestion\s*\(/;
 const HAS_QUESTION_TAG_RE = new RegExp(
   `<(${Object.keys(QUESTION_COMPONENT_REQUIRED).join('|')})(?=[\\s/>])`
 );
+// Custom widget imported from a local `.svelte` file may wrap useQuestion.
+// Treat its presence as enough to suppress the "no questions" warning —
+// false negatives are acceptable for a heuristic that's already advisory.
+const HAS_LOCAL_SVELTE_IMPORT_RE = /from\s+['"][^'"]+\.svelte['"]/;
 
 /**
  * Detect ways an author file can bypass the LMS data contract. These check

package/src/runtime/App.svelte

@@ -177,18 +177,12 @@
     }
   }
 
-  // ---- Quiz completion handler ----
   function handleQuizComplete(e) {
-    const { score, interactions = [] } = e.detail;
+    const { score } = e.detail;
     const pageIndex = nav.currentPageIndex;
     progress.quizCompleted(pageIndex, score);
-    for (const { id, interaction, correct } of interactions) {
-      adapter.reportInteraction(id, interaction, correct);
-    }
     progress.recalculateCompletion(manifest, config);
     progress.recalculateSuccess(manifest, config);
-    // Persistence is scheduled by the version-tracking effect below; no
-    // explicit call needed here.
   }
 
   // ---- Persistence: serialize / restore ----
@@ -403,6 +397,7 @@
       restoreState(saved);
       prevCompletionStatus = progress.completionStatus;
       prevSuccessStatus = progress.successStatus;
+      adapter.seedLifecycle?.(progress.completionStatus, progress.successStatus);
     }
     persistenceReady = true;
 

package/src/runtime/adapters/cmi5.ts

@@ -1,6 +1,10 @@
 import type { PersistenceAdapter, SavedState } from '../persistence.js';
 import type { Interaction } from '../interaction.js';
-import { formatResponse, formatCorrectPattern } from '../interaction-format.js';
+import {
+  formatResponse,
+  formatCorrectPattern,
+  XAPI_INTERACTION_FORMAT,
+} from '../interaction-format.js';
 import { formatISO8601Duration } from './retry.js';
 import { XAPIPublisher } from '../xapi/publisher.js';
 import { X_API_VERSION } from '../xapi/version.js';
@@ -139,8 +143,8 @@ export class CMI5Adapter implements PersistenceAdapter {
   #score: number | null = null;
   #durationSeconds = 0;
   #state: SavedState | null = null;
-  #completedSent = false;
-  #successSent = false;
+  #completedEmitted = false;
+  #lastSuccessEmitted: 'unknown' | 'passed' | 'failed' = 'unknown';
   #terminated = false;
 
   // cmi5 §8 launch params. masteryScore (when present) overrides the
@@ -240,13 +244,28 @@ export class CMI5Adapter implements PersistenceAdapter {
     // Basic credential (already base64); we don't re-encode.
     let token = '';
     if (text.startsWith('{')) {
+      let parsed: unknown;
       try {
-        const parsed = JSON.parse(text);
-        if (parsed && typeof parsed['auth-token'] === 'string') {
-          token = parsed['auth-token'].trim();
-        }
+        parsed = JSON.parse(text);
       } catch {
-        // fall through to legacy parsing
+        parsed = undefined;
+      }
+      if (parsed && typeof parsed === 'object') {
+        const obj = parsed as Record<string, unknown>;
+        if (typeof obj['auth-token'] === 'string') {
+          token = (obj['auth-token'] as string).trim();
+        } else {
+          const code = typeof obj['error-code'] === 'string' ? obj['error-code'] : undefined;
+          const errText = typeof obj['error-text'] === 'string' ? obj['error-text'] : undefined;
+          const detail =
+            code !== undefined || errText !== undefined
+              ? ` (error-code=${code ?? 'unknown'}${errText ? `: ${errText}` : ''})`
+              : '';
+          throw new Error(
+            `Tessera cmi5: fetch URL returned a JSON response without an 'auth-token' field${detail}. ` +
+              'The cmi5 fetch URL is single-use (§8.2.3.1); reload from the LMS to obtain a fresh launch.'
+          );
+        }
       }
     }
     if (!token) {
@@ -434,11 +453,21 @@ export class CMI5Adapter implements PersistenceAdapter {
     this.#score = Math.max(0, Math.min(100, score));
   }
 
+  seedLifecycle(
+    completion: 'incomplete' | 'complete',
+    success: 'unknown' | 'passed' | 'failed'
+  ): void {
+    if (completion === 'complete') this.#completedEmitted = true;
+    if (success === 'passed' || success === 'failed') {
+      this.#lastSuccessEmitted = success;
+    }
+  }
+
   setCompletionStatus(status: 'incomplete' | 'complete'): void {
-    if (status !== 'complete' || this.#completedSent || !this.#publisher) return;
+    if (status !== 'complete' || this.#completedEmitted || !this.#publisher) return;
     // cmi5 §10.2.2 — Browse/Review launches MUST NOT emit Completed.
     if (this.#launchMode !== 'Normal') return;
-    this.#completedSent = true;
+    this.#completedEmitted = true;
     // cmi5 §9.5.1 — `score` MUST NOT appear on Completed (Passed/Failed only).
     const result: Record<string, unknown> = {
       completion: true,
@@ -457,10 +486,11 @@ export class CMI5Adapter implements PersistenceAdapter {
   }
 
   setSuccessStatus(status: 'passed' | 'failed' | 'unknown'): void {
-    if (status === 'unknown' || this.#successSent || !this.#publisher) return;
+    if (status === 'unknown' || !this.#publisher) return;
+    if (status === this.#lastSuccessEmitted) return;
     // cmi5 §10.2.2 — Browse/Review launches MUST NOT emit Passed/Failed.
     if (this.#launchMode !== 'Normal') return;
-    this.#successSent = true;
+    this.#lastSuccessEmitted = status;
 
     const verb = status === 'passed' ? VERBS.passed : VERBS.failed;
     const verbName = status === 'passed' ? 'passed' : 'failed';
@@ -518,8 +548,8 @@ export class CMI5Adapter implements PersistenceAdapter {
     correct: boolean | null
   ): void {
     if (!this.#publisher) return;
-    const response = formatResponse(interaction);
-    const pattern = formatCorrectPattern(interaction);
+    const response = formatResponse(interaction, XAPI_INTERACTION_FORMAT);
+    const pattern = formatCorrectPattern(interaction, XAPI_INTERACTION_FORMAT);
     const definition: Record<string, unknown> = {
       type: CMI_INTERACTION_TYPE,
       interactionType: interaction.type,