tessera-learn 0.0.1

package/src/runtime/interaction-format.ts

@@ -0,0 +1,132 @@
+/**
+ * Format `Interaction` payloads for SCORM 2004 / xAPI `cmi.interactions.n.*`
+ * writes. Delimiters follow SCORM 2004 4th Edition RTE §4.2.7 — `cmi5` (xAPI)
+ * reuses the same encoding for `cmi.interaction` activity statements.
+ *
+ *   ITEM delimiter   [,]
+ *   PAIR delimiter   [.]
+ *   RANGE delimiter  [:]
+ */
+
+import type { Interaction } from './interaction.js';
+
+/**
+ * Serialize the learner response to the `learner_response` / `student_response`
+ * field format expected by SCORM 2004 and mirrored by xAPI.
+ */
+export function formatResponse(i: Interaction): string {
+  switch (i.type) {
+    case 'choice':
+    case 'sequencing':
+      return i.response.join('[,]');
+    case 'true-false':
+      return i.response ? 'true' : 'false';
+    case 'fill-in':
+    case 'long-fill-in':
+    case 'likert':
+    case 'other':
+      return i.response;
+    case 'matching':
+      return i.response.map(([l, r]) => `${l}[.]${r}`).join('[,]');
+    case 'numeric':
+      return String(i.response);
+    case 'performance':
+      return i.response.map(([s, v]) => `${s}[.]${v}`).join('[,]');
+  }
+}
+
+/**
+ * Serialize the `correct_responses.0.pattern` for this interaction. Returns
+ * `null` if no correct pattern was provided.
+ */
+export function formatCorrectPattern(i: Interaction): string | null {
+  if (i.correct === undefined) return null;
+  switch (i.type) {
+    case 'choice':
+    case 'sequencing':
+      return (i.correct as string[]).join('[,]');
+    case 'true-false':
+      return (i.correct as boolean) ? 'true' : 'false';
+    case 'fill-in':
+    case 'long-fill-in':
+      // SCORM 2004 accepts multiple acceptable patterns joined with `[,]`.
+      return (i.correct as string[]).join('[,]');
+    case 'matching':
+      return (i.correct as Array<[string, string]>).map(([l, r]) => `${l}[.]${r}`).join('[,]');
+    case 'numeric': {
+      const c = i.correct as { min?: number; max?: number };
+      const min = c.min ?? '';
+      const max = c.max ?? '';
+      return `${min}[:]${max}`;
+    }
+    case 'likert':
+    case 'other':
+      return i.correct as string;
+    case 'performance':
+      return (i.correct as Array<[string, string | number]>)
+        .map(([s, v]) => `${s}[.]${v}`)
+        .join('[,]');
+  }
+}
+
+/**
+ * Map Tessera interaction types to SCORM 1.2's narrower vocabulary. SCORM 1.2
+ * does not define `long-fill-in`; fall back to `fill-in`. `other` is not in
+ * the spec either — fall back to `fill-in` (free text).
+ */
+export function scorm12Type(type: Interaction['type']): string {
+  switch (type) {
+    case 'long-fill-in':
+      return 'fill-in';
+    case 'other':
+      return 'fill-in';
+    default:
+      return type;
+  }
+}
+
+/**
+ * Per-standard differences in how `cmi.interactions.n.*` is written. The
+ * SCORM 1.2 vs 2004 deltas are: response field name, result vocabulary,
+ * timestamp field name+format, and the type vocabulary mapping.
+ */
+export interface ScormInteractionSpec {
+  responseField: 'student_response' | 'learner_response';
+  timestampField: 'time' | 'timestamp';
+  /** Wall-clock value formatted to whichever style the standard expects. */
+  timestamp: string;
+  /** Mapped interaction type — already narrowed for SCORM 1.2 callers. */
+  typeValue: string;
+  resultLabels: { correct: string; incorrect: string };
+}
+
+/**
+ * Build the ordered list of `cmi.interactions.n.*` writes that SCORM 1.2 and
+ * SCORM 2004 adapters share. Caller wires each pair through its own LMS
+ * SetValue queue (the queueing semantics differ between adapters).
+ */
+export function buildScormInteractionFields(
+  prefix: string,
+  questionId: string,
+  interaction: Interaction,
+  correct: boolean | null,
+  spec: ScormInteractionSpec
+): Array<[string, string]> {
+  const fields: Array<[string, string]> = [
+    [`${prefix}.id`, questionId],
+    [`${prefix}.type`, spec.typeValue],
+    [`${prefix}.${spec.responseField}`, formatResponse(interaction)],
+  ];
+  const pattern = formatCorrectPattern(interaction);
+  if (pattern !== null) {
+    fields.push([`${prefix}.correct_responses.0.pattern`, pattern]);
+  }
+  if (correct !== null) {
+    fields.push([
+      `${prefix}.result`,
+      correct ? spec.resultLabels.correct : spec.resultLabels.incorrect,
+    ]);
+  }
+  fields.push([`${prefix}.${spec.timestampField}`, spec.timestamp]);
+  return fields;
+}

package/src/runtime/interaction.ts

@@ -0,0 +1,96 @@
+/**
+ * Learner interaction data — the payload `useQuestion` returns to the runtime
+ * and that adapters translate into SCORM `cmi.interactions.n.*` or xAPI
+ * `cmi.interaction` activity statements.
+ *
+ * Variants follow the SCORM 2004 4th Edition vocabulary (RTE §4.2.7) verbatim
+ * so there is no impedance mismatch when writing to an LMS.
+ */
+export type Interaction =
+  | { type: 'choice';       response: string[]; correct?: string[] }
+  | { type: 'true-false';   response: boolean;  correct?: boolean }
+  | { type: 'fill-in';      response: string;   correct?: string[]; caseMatters?: boolean }
+  | { type: 'long-fill-in'; response: string;   correct?: string[]; caseMatters?: boolean }
+  | { type: 'matching';     response: Array<[string, string]>; correct?: Array<[string, string]> }
+  | { type: 'sequencing';   response: string[]; correct?: string[] }
+  | { type: 'numeric';      response: number;   correct?: { min?: number; max?: number } }
+  | { type: 'likert';       response: string;   correct?: string }
+  | { type: 'performance';  response: Array<[string, string | number]>; correct?: Array<[string, string | number]> }
+  | { type: 'other';        response: string;   correct?: string };
+
+/**
+ * Decide whether a learner response is correct. Returns:
+ *  - `true`  — response matches the correct pattern
+ *  - `false` — response does not match
+ *  - `null`  — `correct` was not provided; the author will decide externally
+ */
+export function isCorrect(i: Interaction): boolean | null {
+  switch (i.type) {
+    case 'choice':
+      if (i.correct === undefined) return null;
+      return setEqual(i.response, i.correct);
+    case 'true-false':
+      if (i.correct === undefined) return null;
+      return i.response === i.correct;
+    case 'fill-in':
+    case 'long-fill-in': {
+      if (i.correct === undefined) return null;
+      const matters = !!i.caseMatters;
+      const actual = matters ? i.response : i.response.toLowerCase();
+      return i.correct.some((c) => (matters ? c : c.toLowerCase()) === actual);
+    }
+    case 'matching': {
+      if (i.correct === undefined) return null;
+      return pairSetEqual(i.response, i.correct);
+    }
+    case 'sequencing': {
+      if (i.correct === undefined) return null;
+      if (i.response.length !== i.correct.length) return false;
+      for (let k = 0; k < i.response.length; k++) {
+        if (i.response[k] !== i.correct[k]) return false;
+      }
+      return true;
+    }
+    case 'numeric': {
+      if (i.correct === undefined) return null;
+      const { min, max } = i.correct;
+      if (min !== undefined && i.response < min) return false;
+      if (max !== undefined && i.response > max) return false;
+      return true;
+    }
+    case 'likert':
+      if (i.correct === undefined) return null;
+      return i.response === i.correct;
+    case 'performance': {
+      if (i.correct === undefined) return null;
+      if (i.response.length !== i.correct.length) return false;
+      const cmap = new Map<string, string | number>(i.correct);
+      for (const [stepId, value] of i.response) {
+        if (!cmap.has(stepId)) return false;
+        if (cmap.get(stepId) !== value) return false;
+      }
+      return true;
+    }
+    case 'other':
+      if (i.correct === undefined) return null;
+      return i.response === i.correct;
+  }
+}
+
+function setEqual(a: string[], b: string[]): boolean {
+  if (a.length !== b.length) return false;
+  const seen = new Set(b);
+  for (const x of a) if (!seen.has(x)) return false;
+  return true;
+}
+
+function pairSetEqual(
+  a: Array<[string, string]>,
+  b: Array<[string, string]>
+): boolean {
+  if (a.length !== b.length) return false;
+  const key = ([l, r]: [string, string]) => `${l}\u241F${r}`;
+  const bset = new Set(b.map(key));
+  for (const p of a) if (!bset.has(key(p))) return false;
+  return true;
+}

package/src/runtime/navigation.svelte.ts

@@ -0,0 +1,117 @@
+import type { Manifest } from '../plugin/manifest.js';
+import type { CourseConfig } from './types.js';
+import { ProgressState } from './progress.svelte.js';
+
+export function isPageComplete(
+  index: number,
+  manifest: Manifest,
+  progress: ProgressState,
+  config: CourseConfig
+): boolean {
+  const page = manifest.pages[index];
+  if (!page) return false;
+
+  if (!page.quiz) {
+    return progress.visitedPages.has(index);
+  }
+
+  if (!page.quiz.gatesProgress) {
+    return progress.quizScores.has(index);
+  }
+
+  return (progress.quizScores.get(index) ?? 0) >= config.scoring.passingScore;
+}
+
+export class NavigationState {
+  manifest = $state<Manifest>(null!);
+  #progress: ProgressState;
+  #config: CourseConfig;
+  currentPageIndex = $state(0);
+
+  canGoPrev = $derived(this.currentPageIndex > 0);
+
+  canGoNext = $derived.by(() => {
+    const next = this.currentPageIndex + 1;
+    if (next >= this.manifest.totalPages) return false;
+    return !this.isPageLocked(next);
+  });
+
+  // Cache locked-page lookup as a single derived Set so the sidebar's
+  // per-page `isPageLocked` calls stay O(1). Without this, sequential mode
+  // is O(n²) per render (each `isPageLocked` walks all earlier pages).
+  // Recomputed once per relevant state change.
+  #lockedSet = $derived.by<Set<number>>(() => this.#computeLockedSet());
+
+  constructor(manifest: Manifest, progress: ProgressState, config: CourseConfig) {
+    this.manifest = manifest;
+    this.#progress = progress;
+    this.#config = config;
+  }
+
+  goToPage(index: number) {
+    if (index < 0 || index >= this.manifest.totalPages) return;
+    if (this.isPageLocked(index)) return;
+    this.currentPageIndex = index;
+  }
+
+  goNext() {
+    if (this.canGoNext) this.goToPage(this.currentPageIndex + 1);
+  }
+
+  goPrev() {
+    if (this.canGoPrev) this.goToPage(this.currentPageIndex - 1);
+  }
+
+  isPageLocked(index: number): boolean {
+    return this.#lockedSet.has(index);
+  }
+
+  // Compute the locked set in a single forward pass. The built-in modes are
+  // expressed inline (rather than calling resolveAccess/freeAccess/sequential
+  // per page) so the whole walk is O(n). Custom predicates fall back to a
+  // per-page evaluation since their semantics are arbitrary — but it still
+  // runs once per state change rather than once per page per render.
+  #computeLockedSet(): Set<number> {
+    const total = this.manifest.totalPages;
+    const locked = new Set<number>();
+
+    if (this.#config.navigation.canAccess) {
+      const fn = this.#config.navigation.canAccess;
+      for (let i = 0; i < total; i++) {
+        if (!fn({
+          pageIndex: i,
+          page: this.manifest.pages[i],
+          manifest: this.manifest,
+          progress: this.#progress,
+          config: this.#config,
+        })) {
+          locked.add(i);
+        }
+      }
+      return locked;
+    }
+
+    if (this.#config.navigation.mode === 'sequential') {
+      // Once any page is incomplete, every later page is locked.
+      for (let i = 1; i < total; i++) {
+        if (!isPageComplete(i - 1, this.manifest, this.#progress, this.#config)) {
+          for (let k = i; k < total; k++) locked.add(k);
+          return locked;
+        }
+      }
+      return locked;
+    }
+
+    // Free mode: a page is locked iff its most-recent gating quiz is unmet.
+    let lastGatingUnmet = false;
+    for (let i = 0; i < total; i++) {
+      if (lastGatingUnmet) locked.add(i);
+      const page = this.manifest.pages[i];
+      if (page.quiz?.gatesProgress) {
+        const score = this.#progress.quizScores.get(i) ?? 0;
+        lastGatingUnmet = score < this.#config.scoring.passingScore;
+      }
+    }
+    return locked;
+  }
+}

package/src/runtime/persistence.ts

@@ -0,0 +1,56 @@
+/**
+ * Persistence API — interface for saving/restoring course state.
+ */
+
+import type { Interaction } from './interaction.js';
+
+export interface PersistenceAdapter {
+  init(): Promise<void>;
+  getState(): SavedState | null;
+  saveState(state: SavedState): void;
+  setScore(score: number): void;
+  setCompletionStatus(status: 'incomplete' | 'complete'): void;
+  setSuccessStatus(status: 'passed' | 'failed' | 'unknown'): void;
+  setDuration(seconds: number): void;
+  /**
+   * Tell the LMS how the learner is leaving the SCO. SCORM 1.2 maps
+   * `'suspend'` → `cmi.core.exit = 'suspend'`, `'normal'` → empty (the
+   * vocabulary has no explicit normal value). SCORM 2004 maps directly
+   * onto `cmi.exit`. cmi5 / web adapters no-op.
+   */
+  setExit(mode: 'suspend' | 'normal'): void;
+  /**
+   * Report a single learner interaction (answered question) to the LMS.
+   * Called once per question on quiz submit or standalone useQuestion submit.
+   */
+  reportInteraction(
+    questionId: string,
+    interaction: Interaction,
+    correct: boolean | null
+  ): void;
+  commit(): void;
+  terminate(): void;
+}
+
+/**
+ * Compact serialization format for course state.
+ * Single-letter keys to minimize storage footprint (SCORM 1.2 suspend_data is 4KB).
+ */
+export interface SavedState {
+  /** Bookmark — current page index */
+  b: number;
+  /** Visited — array of page indices */
+  v: number[];
+  /** Quiz scores — pageIndex (as string key) to score */
+  q: Record<string, number>;
+  /** Duration — accumulated seconds */
+  d: number;
+  /** Chunk progress — pageIndex (as string key) to highest revealed chunk index */
+  c?: Record<string, number>;
+  /** User-scoped state written via `usePersistence(key)`, keyed by caller. */
+  u?: Record<string, unknown>;
+  /** Standalone question scores — pageIndex → (questionId → score 0-100) */
+  s?: Record<string, Record<string, number>>;
+  /** Graded standalone page indices — pages with at least one graded standalone question */
+  gs?: number[];
+}

package/src/runtime/progress.svelte.ts

@@ -0,0 +1,168 @@
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+import type { Manifest } from '../plugin/manifest.js';
+import type { CourseConfig } from './types.js';
+
+export class ProgressState {
+  visitedPages = $state(new SvelteSet<number>());
+  quizScores = $state(new SvelteMap<number, number>());
+  /**
+   * Chunk progress — for pages that reveal content in stages (Continue buttons).
+   * Maps pageIndex → highest revealed chunk index (0-based).
+   */
+  chunkProgress = $state(new SvelteMap<number, number>());
+  /**
+   * Per-page standalone question scores from `useQuestion`. pageIndex → (questionId → score 0-100).
+   * Tracked separately from `quizScores` because <Quiz> blocks score as a unit
+   * while standalone questions score individually and average per page.
+   */
+  standaloneQuestionScores = $state(new SvelteMap<number, Map<string, number>>());
+  /**
+   * Set of page indices that have at least one graded standalone question.
+   * Pages in this set contribute to course success status via their standalone average.
+   */
+  gradedStandalonePages = $state(new SvelteSet<number>());
+  completionStatus = $state<'incomplete' | 'complete'>('incomplete');
+  successStatus = $state<'unknown' | 'passed' | 'failed'>('unknown');
+
+  /**
+   * Monotonic counter incremented on every persistable state mutation
+   * (visited/scores/chunks/standalone). Callers that need to react to *any*
+   * progress change can subscribe to this single signal instead of iterating
+   * each Map/Set themselves.
+   */
+  version = $state(0);
+
+  /**
+   * Mark a page as visited. Callers must call recalculateCompletion()
+   * afterward to update completionStatus.
+   */
+  markVisited(pageIndex: number) {
+    if (this.visitedPages.has(pageIndex)) return;
+    this.visitedPages.add(pageIndex);
+    this.version++;
+  }
+
+  /**
+   * Record a quiz score. Callers must call recalculateCompletion()
+   * and recalculateSuccess() afterward to update status fields.
+   */
+  quizCompleted(pageIndex: number, score: number) {
+    this.quizScores.set(pageIndex, score);
+    this.version++;
+  }
+
+  /**
+   * Record the highest chunk index revealed on a page. Idempotent — only
+   * advances forward, never backward.
+   */
+  markChunk(pageIndex: number, chunkIndex: number) {
+    const current = this.chunkProgress.get(pageIndex) ?? -1;
+    if (chunkIndex <= current) return;
+    this.chunkProgress.set(pageIndex, chunkIndex);
+    this.version++;
+  }
+
+  /** Highest chunk revealed on a page, or -1 if none. */
+  getChunk(pageIndex: number): number {
+    return this.chunkProgress.get(pageIndex) ?? -1;
+  }
+
+  /**
+   * Record the score for a single standalone question (one created via
+   * `useQuestion` outside a `<Quiz>`). When `graded`, the page is added to
+   * `gradedStandalonePages` so it contributes to course success.
+   */
+  markStandaloneQuestion(
+    pageIndex: number,
+    questionId: string,
+    score: number,
+    graded: boolean
+  ) {
+    let pageMap = this.standaloneQuestionScores.get(pageIndex);
+    if (!pageMap) {
+      pageMap = new Map<string, number>();
+      this.standaloneQuestionScores.set(pageIndex, pageMap);
+    }
+    pageMap.set(questionId, score);
+    if (graded) {
+      this.gradedStandalonePages.add(pageIndex);
+    }
+    this.version++;
+  }
+
+  /** Average of standalone question scores on a page, or 0 if none. */
+  getPageStandaloneAverage(pageIndex: number): number {
+    const pageMap = this.standaloneQuestionScores.get(pageIndex);
+    if (!pageMap || pageMap.size === 0) return 0;
+    let sum = 0;
+    for (const s of pageMap.values()) sum += s;
+    return sum / pageMap.size;
+  }
+
+  recalculateCompletion(manifest: Manifest, config: CourseConfig) {
+    if (config.completion.mode === 'percentage') {
+      const threshold = config.completion.percentageThreshold ?? 100;
+      const percent = manifest.totalPages > 0
+        ? (this.visitedPages.size / manifest.totalPages) * 100
+        : 0;
+      this.completionStatus = percent >= threshold ? 'complete' : 'incomplete';
+    } else if (config.completion.mode === 'quiz') {
+      const { indices } = this.#gradedPages(manifest);
+      if (indices.length === 0) {
+        this.completionStatus = 'incomplete';
+        return;
+      }
+      const average = this.#gradedAverage(indices);
+      this.completionStatus = average >= config.scoring.passingScore ? 'complete' : 'incomplete';
+    }
+  }
+
+  recalculateSuccess(manifest: Manifest, config: CourseConfig) {
+    const { indices, attempted } = this.#gradedPages(manifest);
+
+    if (indices.length === 0) {
+      this.successStatus = 'unknown';
+      return;
+    }
+    // Stay unknown until at least one graded score has been recorded
+    if (!attempted) {
+      this.successStatus = 'unknown';
+      return;
+    }
+    const average = this.#gradedAverage(indices);
+    this.successStatus = average >= config.scoring.passingScore ? 'passed' : 'failed';
+  }
+
+  /**
+   * Union of pages that contribute to graded scoring: pageConfig graded quizzes
+   * plus pages with at least one graded standalone question (deduped).
+   * `attempted` is true if any of those pages has a recorded score.
+   */
+  #gradedPages(manifest: Manifest): { indices: number[]; attempted: boolean } {
+    const quizPages = manifest.pages.filter(p => p.quiz?.graded).map(p => p.index);
+    const indices = [...new Set([...quizPages, ...this.gradedStandalonePages])];
+    const attempted = indices.some(i => this.#hasScore(i));
+    return { indices, attempted };
+  }
+
+  /** Whether a page has any recorded graded score (quiz or standalone). */
+  #hasScore(pageIndex: number): boolean {
+    if (this.quizScores.has(pageIndex)) return true;
+    const pageMap = this.standaloneQuestionScores.get(pageIndex);
+    return !!pageMap && pageMap.size > 0;
+  }
+
+  /**
+   * Average across the given page indices. Each page contributes its quiz score
+   * if present, otherwise its standalone average. Pages with no recorded score
+   * contribute 0 (matching the existing "unattempted graded quiz = 0" rule).
+   */
+  #gradedAverage(indices: number[]): number {
+    if (indices.length === 0) return 0;
+    let sum = 0;
+    for (const i of indices) {
+      sum += this.quizScores.get(i) ?? this.getPageStandaloneAverage(i);
+    }
+    return sum / indices.length;
+  }
+}