tessera-learn 0.0.3 → 0.0.4

package/src/plugin/validation.ts

@@ -32,8 +32,10 @@ const KNOWN_CONFIG_FIELDS = new Set([
 ]);
 
 const VALID_NAV_MODES = ['free', 'sequential'];
-const VALID_COMPLETION_MODES = ['quiz', 'percentage'];
+const VALID_COMPLETION_MODES = ['quiz', 'percentage', 'manual'];
 const VALID_EXPORT_STANDARDS = ['web', 'scorm12', 'scorm2004', 'cmi5'];
+const VALID_MANUAL_TRIGGERS = ['page'];
+const VALID_REQUIRE_SUCCESS_STATUS = ['passed', 'failed'];
 
 // ---------- Main ----------
 
@@ -75,7 +77,12 @@ export function validateProject(projectRoot: string): ValidationResult {
 interface ParsedConfig {
   title?: string;
   navigation?: { mode?: string };
-  completion?: { mode?: string; percentageThreshold?: number };
+  completion?: {
+    mode?: string;
+    percentageThreshold?: number;
+    trigger?: string;
+    requireSuccessStatus?: string;
+  };
   scoring?: { passingScore?: number };
   export?: { standard?: string };
   [key: string]: unknown;
@@ -126,7 +133,31 @@ function parseConfig(
   if (config.completion?.mode !== undefined) {
     if (!VALID_COMPLETION_MODES.includes(config.completion.mode)) {
       errors.push(
-        `course.config.js: "completion.mode" must be "quiz" or "percentage", got "${config.completion.mode}"`
+        `course.config.js: "completion.mode" must be "quiz", "percentage", or "manual", got "${config.completion.mode}"`
+      );
+    }
+  }
+
+  if (config.completion?.trigger !== undefined) {
+    if (config.completion.mode !== 'manual') {
+      warnings.push(
+        `course.config.js: "completion.trigger" is ignored unless completion.mode is "manual"`
+      );
+    } else if (!VALID_MANUAL_TRIGGERS.includes(config.completion.trigger)) {
+      errors.push(
+        `course.config.js: "completion.trigger" must be "page" or omitted, got "${config.completion.trigger}"`
+      );
+    }
+  }
+
+  if (config.completion?.requireSuccessStatus !== undefined) {
+    if (config.completion.mode !== 'manual') {
+      warnings.push(
+        `course.config.js: "completion.requireSuccessStatus" is ignored unless completion.mode is "manual"`
+      );
+    } else if (!VALID_REQUIRE_SUCCESS_STATUS.includes(config.completion.requireSuccessStatus)) {
+      errors.push(
+        `course.config.js: "completion.requireSuccessStatus" must be "passed" or "failed" (omit for "unknown"), got "${config.completion.requireSuccessStatus}"`
       );
     }
   }
@@ -452,10 +483,19 @@ function validateSingleXAPIEntry(
 
 // ---------- Pages Validation ----------
 
+interface PageInfo {
+  fileRel: string;
+  navIndex: number;
+  hasGradedQuiz: boolean;
+  hasQuiz: boolean;
+  completesOnView: boolean;
+}
+
 interface PagesValidationResult extends ValidationResult {
   totalPages: number;
   totalQuizzes: number;
   hasGradedQuiz: boolean;
+  pages: PageInfo[];
 }
 
 function validatePages(
@@ -465,6 +505,7 @@ function validatePages(
 ): PagesValidationResult {
   const errors: string[] = [];
   const warnings: string[] = [];
+  const pages: PageInfo[] = [];
   let totalPages = 0;
   let totalQuizzes = 0;
   let hasGradedQuiz = false;
@@ -475,7 +516,7 @@ function validatePages(
     errors.push(
       'No pages found. Create at least one section with a lesson and page in pages/'
     );
-    return { errors, warnings, totalPages: 0, totalQuizzes: 0, hasGradedQuiz: false };
+    return { errors, warnings, totalPages: 0, totalQuizzes: 0, hasGradedQuiz: false, pages };
   }
 
   const topLevelEntries = readdirSync(pagesDir);
@@ -503,7 +544,7 @@ function validatePages(
     errors.push(
       'No pages found. Create at least one section with a lesson and page in pages/'
     );
-    return { errors, warnings, totalPages: 0, totalQuizzes: 0, hasGradedQuiz: false };
+    return { errors, warnings, totalPages: 0, totalQuizzes: 0, hasGradedQuiz: false, pages };
   }
 
   for (const sectionName of sectionDirs) {
@@ -545,16 +586,28 @@ function validatePages(
       const content = readSourceFileCached(filePath);
 
       const pageConfig = validatePageConfig(content, fileRel, errors);
+      const navIndex = totalPages;
       totalPages++;
 
+      let pageHasGradedQuiz = false;
       if (pageConfig?.quiz) {
         totalQuizzes++;
         validateQuizConfig(pageConfig.quiz, fileRel, errors);
         if ((pageConfig.quiz as { graded?: unknown }).graded === true) {
           hasGradedQuiz = true;
+          pageHasGradedQuiz = true;
         }
       }
 
+      const completesOnView = validateCompletesOn(pageConfig, fileRel, errors);
+      pages.push({
+        fileRel,
+        navIndex,
+        hasGradedQuiz: pageHasGradedQuiz,
+        hasQuiz: !!pageConfig?.quiz,
+        completesOnView,
+      });
+
       validateAssetRefs(content, fileRel, assetsDir, warnings, assetExistsCache);
     }
 
@@ -615,8 +668,10 @@ function validatePages(
         const content = readSourceFileCached(filePath);
 
         const pageConfig = validatePageConfig(content, fileRel, errors);
+        const navIndex = totalPages;
         totalPages++;
 
+        let pageHasGradedQuiz = false;
         if (pageConfig?.quiz) {
           totalQuizzes++;
 
@@ -625,9 +680,19 @@ function validatePages(
 
           if ((pageConfig.quiz as { graded?: unknown }).graded === true) {
             hasGradedQuiz = true;
+            pageHasGradedQuiz = true;
           }
         }
 
+        const completesOnView = validateCompletesOn(pageConfig, fileRel, errors);
+        pages.push({
+          fileRel,
+          navIndex,
+          hasGradedQuiz: pageHasGradedQuiz,
+          hasQuiz: !!pageConfig?.quiz,
+          completesOnView,
+        });
+
         // Check $assets references
         validateAssetRefs(content, fileRel, assetsDir, warnings, assetExistsCache);
       }
@@ -640,7 +705,7 @@ function validatePages(
     );
   }
 
-  return { errors, warnings, totalPages, totalQuizzes, hasGradedQuiz };
+  return { errors, warnings, totalPages, totalQuizzes, hasGradedQuiz, pages };
 }
 
 // ---------- _meta.js Validation ----------
@@ -681,7 +746,7 @@ function validatePageConfig(
   content: string,
   fileRel: string,
   errors: string[]
-): { title?: string; quiz?: unknown } | null {
+): { title?: string; quiz?: unknown; completesOn?: unknown } | null {
   const result = parsePageConfigFromSource(content);
   if (result.kind === 'ok') return result.value;
   if (result.kind === 'invalid') {
@@ -692,6 +757,19 @@ function validatePageConfig(
   return null;
 }
 
+function validateCompletesOn(
+  pageConfig: { completesOn?: unknown } | null,
+  fileRel: string,
+  errors: string[]
+): boolean {
+  if (!pageConfig || pageConfig.completesOn === undefined) return false;
+  if (pageConfig.completesOn === 'view') return true;
+  errors.push(
+    `${fileRel}: pageConfig.completesOn must be "view", got ${JSON.stringify(pageConfig.completesOn)}`
+  );
+  return false;
+}
+
 // ---------- Quiz Config Validation ----------
 
 function validateQuizConfig(quiz: unknown, fileRel: string, errors: string[]): void {
@@ -766,6 +844,58 @@ function crossValidate(
     );
   }
 
+  const isManual = config.completion?.mode === 'manual';
+  const completesOnPages = pageResults.pages.filter((p) => p.completesOnView);
+
+  if (isManual && config.completion?.trigger === 'page' && completesOnPages.length === 0) {
+    errors.push(
+      'completion.mode is "manual" with trigger: "page", but no page declares pageConfig.completesOn: "view". ' +
+        'Either add a completesOn page or remove the trigger field to drop the static check.'
+    );
+  }
+
+  if (isManual) {
+    for (const page of pageResults.pages) {
+      if (page.hasGradedQuiz) {
+        warnings.push(
+          `${page.fileRel}: quiz.graded is true under completion.mode: "manual". ` +
+            'The score will be reported to the LMS for transcripts, but it will not drive ' +
+            'completion or success status — `markComplete()` / completesOn does. If that\'s ' +
+            'not what you want, set graded: false or change completion.mode.'
+        );
+      }
+    }
+  }
+
+  if (isManual && config.completion?.percentageThreshold !== undefined) {
+    warnings.push(
+      'course.config.js: "completion.percentageThreshold" is ignored under completion.mode: "manual"'
+    );
+  }
+  if (!isManual) {
+    for (const page of completesOnPages) {
+      warnings.push(
+        `${page.fileRel}: pageConfig.completesOn is ignored — completion.mode is "${config.completion?.mode ?? 'percentage'}"`
+      );
+    }
+  }
+  for (const page of pageResults.pages) {
+    if (page.completesOnView && page.hasQuiz) {
+      warnings.push(
+        `${page.fileRel}: completion fires on view, before the quiz can be answered — likely a mistake`
+      );
+    }
+  }
+
+  if (isManual) {
+    const firstPage = pageResults.pages.find((p) => p.navIndex === 0);
+    if (firstPage?.completesOnView) {
+      warnings.push(
+        `${firstPage.fileRel}: pageConfig.completesOn: "view" is on the first page — the course will complete immediately on launch, before the learner sees any other content.`
+      );
+    }
+  }
+
   // SCORM 1.2 + high page count warning
   if (config.export?.standard === 'scorm12') {
     // Estimate worst-case suspend_data size when all pages are visited, all

package/src/runtime/App.svelte

@@ -102,8 +102,13 @@
       if (gen !== loadGeneration) return; // stale
       PageComponent = mod.default;
       pageLoading = false;
-      // Mark visited and recalculate
       progress.markVisited(index);
+      if (
+        manifest.pages[index].completesOn === 'view' &&
+        config.completion.mode === 'manual'
+      ) {
+        progress.markCompleteManually();
+      }
       progress.recalculateCompletion(manifest, config);
       progress.recalculateSuccess(manifest, config);
     }).catch(err => {
@@ -211,6 +216,7 @@
       s,
       gs: [...progress.gradedStandalonePages],
       u: { ...userState },
+      ...(progress.manuallyCompleted ? { m: 1 } : {}),
     };
   }
 
@@ -246,6 +252,10 @@
     }
     // Restore duration
     duration = new DurationTracker(saved.d || 0);
+    // Must come before recalc so manual-mode branches see the latch.
+    if (saved.m === 1) {
+      progress.markCompleteManually();
+    }
     // Recalculate derived state
     progress.recalculateCompletion(manifest, config);
     progress.recalculateSuccess(manifest, config);
@@ -303,7 +313,10 @@
 
     untrack(() => {
       adapter.setScore(Math.round(average));
-      adapter.setSuccessStatus(average >= config.scoring.passingScore ? 'passed' : 'failed');
+      // Under manual mode, success is owned by requireSuccessStatus.
+      if (config.completion.mode !== 'manual') {
+        adapter.setSuccessStatus(average >= config.scoring.passingScore ? 'passed' : 'failed');
+      }
       adapter.setDuration(duration.sessionSeconds);
       adapter.commit();
     });
@@ -322,8 +335,21 @@
     });
   });
 
+  let prevSuccessStatus = $state('unknown');
+  $effect(() => {
+    const status = progress.successStatus;
+    if (!persistenceReady) return;
+    if (status === prevSuccessStatus) return;
+    prevSuccessStatus = status;
+    untrack(() => {
+      adapter.setSuccessStatus(status);
+      adapter.commit();
+    });
+  });
+
   // ---- Exit / Terminate lifecycle ----
   let terminated = false;
+  let manualWatchdog = null;
 
   function handleExit() {
     if (terminated) return;
@@ -360,10 +386,23 @@
       pageLoading = false;
       return;
     }
+
+    // cmi5 §8: an LMS-supplied masteryScore is the authoritative pass
+    // threshold for this launch and overrides the manifest. Mutate the
+    // imported config object once before any UI reads it so every
+    // downstream consumer (recalculateSuccess, navigation gating, Quiz
+    // page context) sees the same effective value.
+    const lmsMastery = adapter.getMasteryScore?.();
+    if (typeof lmsMastery === 'number') {
+      config.scoring.passingScore = lmsMastery * 100;
+      pageContext.passingScore = lmsMastery * 100;
+    }
+
     const saved = adapter.getState();
     if (saved) {
       restoreState(saved);
       prevCompletionStatus = progress.completionStatus;
+      prevSuccessStatus = progress.successStatus;
     }
     persistenceReady = true;
 
@@ -390,6 +429,27 @@
     window.addEventListener('beforeunload', handleExit);
     const appEl = document.getElementById('tessera-app');
     appEl?.addEventListener('tessera-quiz-complete', handleQuizComplete);
+
+    // Dev-only watchdog for `completion.mode: "manual"` without an opt-in
+    // trigger check — catches the hook never being called or no completesOn
+    // page being reachable.
+    if (
+      import.meta.env?.DEV &&
+      config.completion.mode === 'manual' &&
+      config.completion.trigger === undefined &&
+      progress.completionStatus === 'incomplete'
+    ) {
+      manualWatchdog = window.setTimeout(() => {
+        if (progress.completionStatus === 'incomplete') {
+          console.warn(
+            '[tessera] completion.mode is "manual" but the course has not completed after 60s. ' +
+              'No page declared `pageConfig.completesOn: "view"` was reached, and no component called ' +
+              '`useCompletion().markComplete()`. This is a misconfiguration; set `completion.trigger: "page"` ' +
+              'in course.config.js to fail the build instead of waiting at runtime.'
+          );
+        }
+      }, 60_000);
+    }
   });
 
   onDestroy(() => {
@@ -397,6 +457,10 @@
     window.removeEventListener('beforeunload', handleExit);
     const appEl = document.getElementById('tessera-app');
     appEl?.removeEventListener('tessera-quiz-complete', handleQuizComplete);
+    if (manualWatchdog !== null) {
+      clearTimeout(manualWatchdog);
+      manualWatchdog = null;
+    }
     // Clear the global slot so a stale client from a previous mount
     // can't leak into a fresh one (matters for tests that re-mount).
     registerXAPIClient(null);

package/src/runtime/adapters/cmi5.ts

@@ -17,10 +17,29 @@ const VERBS = {
   failed: 'http://adlnet.gov/expapi/verbs/failed',
   suspended: 'http://adlnet.gov/expapi/verbs/suspended',
   terminated: 'http://adlnet.gov/expapi/verbs/terminated',
+  satisfied: 'https://w3id.org/xapi/adl/verbs/satisfied',
 } as const;
 
 const CMI_INTERACTION_TYPE = 'http://adlnet.gov/expapi/activities/cmi.interaction';
 
+const CMI5_MASTERYSCORE_EXT =
+  'https://w3id.org/xapi/cmi5/context/extensions/masteryscore';
+
+export type CMI5MoveOn =
+  | 'Passed'
+  | 'Completed'
+  | 'CompletedAndPassed'
+  | 'CompletedOrPassed'
+  | 'NotApplicable';
+
+const VALID_MOVE_ON: ReadonlySet<CMI5MoveOn> = new Set([
+  'Passed',
+  'Completed',
+  'CompletedAndPassed',
+  'CompletedOrPassed',
+  'NotApplicable',
+]);
+
 /**
  * CMI5 persistence adapter using xAPI.
  *
@@ -50,8 +69,16 @@ export class CMI5Adapter implements PersistenceAdapter {
   #completedSent = false;
   #completionStatus: 'incomplete' | 'complete' = 'incomplete';
   #successSent = false;
+  #passed = false;
   #terminated = false;
 
+  // cmi5 §8 launch params. masteryScore (when present) overrides the
+  // course's manifest passingScore for this launch — the LMS is the
+  // authority. moveOn drives the optional Satisfied statement (§9.5.3).
+  #masteryScore: number | null = null;
+  #moveOn: CMI5MoveOn = 'NotApplicable';
+  #satisfiedSent = false;
+
   async init(): Promise<void> {
     const params = new URLSearchParams(window.location.search);
     const fetchUrl = params.get('fetch');
@@ -63,6 +90,29 @@ export class CMI5Adapter implements PersistenceAdapter {
     this.#registration = reg ? reg : undefined;
     this.#activityId = params.get('activityId') || '';
 
+    const rawMastery = params.get('masteryScore');
+    if (rawMastery !== null && rawMastery !== '') {
+      const m = Number(rawMastery);
+      if (Number.isFinite(m) && m >= 0 && m <= 1) {
+        this.#masteryScore = m;
+      } else {
+        console.warn(
+          `Tessera cmi5: launch parameter 'masteryScore' is not a decimal in [0,1] (got "${rawMastery}"); ignoring.`
+        );
+      }
+    }
+
+    const rawMoveOn = params.get('moveOn');
+    if (rawMoveOn !== null && rawMoveOn !== '') {
+      if (VALID_MOVE_ON.has(rawMoveOn as CMI5MoveOn)) {
+        this.#moveOn = rawMoveOn as CMI5MoveOn;
+      } else {
+        console.warn(
+          `Tessera cmi5: launch parameter 'moveOn' is not a recognized value (got "${rawMoveOn}"); defaulting to NotApplicable.`
+        );
+      }
+    }
+
     // Malformed actor JSON is a launch-time failure: an empty {} actor
     // would fail every Identified-Agent check downstream and produce
     // confusing 400s on every send. Fail loud here instead.
@@ -156,6 +206,21 @@ export class CMI5Adapter implements PersistenceAdapter {
     return this.#publisher;
   }
 
+  /**
+   * LMS-supplied masteryScore from the cmi5 launch URL (a decimal in
+   * [0, 1]), or null when omitted. When present, the runtime should treat
+   * it as the authoritative pass threshold for this session, overriding
+   * `course.config.js scoring.passingScore`.
+   */
+  getMasteryScore(): number | null {
+    return this.#masteryScore;
+  }
+
+  /** LMS-supplied moveOn criterion (defaults to "NotApplicable"). */
+  getMoveOn(): CMI5MoveOn {
+    return this.#moveOn;
+  }
+
   getState(): SavedState | null {
     return this.#state;
   }
@@ -197,15 +262,18 @@ export class CMI5Adapter implements PersistenceAdapter {
       .sendStatement({
         verb: { id: VERBS.completed, display: { 'en-US': 'completed' } },
         result,
+        context: this.#masteryContext(),
       })
       .catch((err) => {
         console.warn('Tessera cmi5: failed to send Completed statement', err);
       });
+    this.#maybeSendSatisfied();
   }
 
   setSuccessStatus(status: 'passed' | 'failed' | 'unknown'): void {
     if (status === 'unknown' || this.#successSent || !this.#publisher) return;
     this.#successSent = true;
+    this.#passed = status === 'passed';
 
     const verb = status === 'passed' ? VERBS.passed : VERBS.failed;
     const verbName = status === 'passed' ? 'passed' : 'failed';
@@ -220,10 +288,12 @@ export class CMI5Adapter implements PersistenceAdapter {
       .sendStatement({
         verb: { id: verb, display: { 'en-US': verbName } },
         result,
+        context: this.#masteryContext(),
       })
       .catch((err) => {
         console.warn(`Tessera cmi5: failed to send ${verbName} statement`, err);
       });
+    this.#maybeSendSatisfied();
   }
 
   setDuration(seconds: number): void {
@@ -305,6 +375,56 @@ export class CMI5Adapter implements PersistenceAdapter {
 
   // ---- Private helpers ----
 
+  /**
+   * Build a context object carrying the cmi5 masteryscore extension when
+   * the LMS provided one. Returns undefined otherwise so the publisher
+   * doesn't add an empty `context.extensions` block.
+   */
+  #masteryContext(): Record<string, unknown> | undefined {
+    if (this.#masteryScore === null) return undefined;
+    return {
+      extensions: { [CMI5_MASTERYSCORE_EXT]: this.#masteryScore },
+    };
+  }
+
+  /**
+   * cmi5 §9.5.3: when the moveOn criterion has been met, the AU MAY send
+   * a Satisfied statement so LMSes that don't compute moveOn themselves
+   * still see satisfaction. NotApplicable disables emission entirely.
+   */
+  #maybeSendSatisfied(): void {
+    if (this.#satisfiedSent || !this.#publisher) return;
+    if (this.#moveOn === 'NotApplicable') return;
+
+    let satisfied = false;
+    switch (this.#moveOn) {
+      case 'Passed':
+        satisfied = this.#passed;
+        break;
+      case 'Completed':
+        satisfied = this.#completedSent;
+        break;
+      case 'CompletedAndPassed':
+        satisfied = this.#completedSent && this.#passed;
+        break;
+      case 'CompletedOrPassed':
+        satisfied = this.#completedSent || this.#passed;
+        break;
+    }
+    if (!satisfied) return;
+
+    this.#satisfiedSent = true;
+    this.#publisher
+      .sendStatement({
+        verb: { id: VERBS.satisfied, display: { 'en-US': 'satisfied' } },
+        result: { duration: formatISO8601Duration(this.#durationSeconds) },
+        context: this.#masteryContext(),
+      })
+      .catch((err) => {
+        console.warn('Tessera cmi5: failed to send Satisfied statement', err);
+      });
+  }
+
   #buildStateUrl(): string {
     const agentJson = JSON.stringify(this.#actor);
     const params = new URLSearchParams({

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

@@ -9,6 +9,16 @@ export interface ScormDialect<TApi> {
   sessionTimeKey: string;
   /** Format `seconds` for the session-time field — HHMMSS for 1.2, ISO8601 for 2004. */
   formatDuration(seconds: number): string;
+  /**
+   * Per-spec maximum byte length for `cmi.suspend_data` (SCORM 1.2 RTE
+   * §3.4.5.2 = 4096; SCORM 2004 4E §4.2 = 64000). Used by `saveState` to
+   * warn once when the serialized payload would be silently truncated by
+   * the LMS. Treated as "characters" since SCORM data-model lengths are
+   * specified in characters and Tessera stores ASCII-safe JSON.
+   */
+  suspendDataLimit: number;
+  /** Human label for the limit warning, e.g. "SCORM 1.2 (4096 chars)". */
+  suspendDataLimitLabel: string;
   /** Per-interaction-row field config passed to `buildScormInteractionFields`. */
   interactionFields: {
     responseField: 'student_response' | 'learner_response';
@@ -34,6 +44,7 @@ export abstract class BaseScormAdapter<TApi> implements PersistenceAdapter {
   protected readonly queue = new WriteQueue();
   #state: SavedState | null = null;
   #terminated = false;
+  #suspendOverflowWarned = false;
   protected interactionCount = 0;
 
   constructor(api: TApi, dialect: ScormDialect<TApi>) {
@@ -84,6 +95,19 @@ export abstract class BaseScormAdapter<TApi> implements PersistenceAdapter {
   saveState(state: SavedState): void {
     this.#state = state;
     const json = JSON.stringify(state);
+    if (
+      !this.#suspendOverflowWarned &&
+      json.length > this.dialect.suspendDataLimit
+    ) {
+      this.#suspendOverflowWarned = true;
+      console.warn(
+        `Tessera: cmi.suspend_data is ${json.length} chars, over the ` +
+          `${this.dialect.suspendDataLimitLabel} limit. The LMS will likely ` +
+          `truncate it and the next resume will lose state. Reduce ` +
+          `usePersistence() payloads or switch export.standard to a ` +
+          `larger-limit standard (scorm2004/cmi5).`
+      );
+    }
     this.queue.enqueue(() =>
       this.dialect.setValue(this.api, 'cmi.suspend_data', json)
     );

package/src/runtime/adapters/scorm12.ts

@@ -19,6 +19,8 @@ export interface SCORM12API {
 const SCORM12_DIALECT: ScormDialect<SCORM12API> = {
   sessionTimeKey: 'cmi.core.session_time',
   formatDuration: formatHHMMSS,
+  suspendDataLimit: 4096,
+  suspendDataLimitLabel: 'SCORM 1.2 cmi.suspend_data 4096-char',
   interactionFields: {
     responseField: 'student_response',
     timestampField: 'time',

package/src/runtime/adapters/scorm2004.ts

@@ -18,6 +18,8 @@ export interface SCORM2004API {
 const SCORM2004_DIALECT: ScormDialect<SCORM2004API> = {
   sessionTimeKey: 'cmi.session_time',
   formatDuration: formatISO8601Duration,
+  suspendDataLimit: 64000,
+  suspendDataLimitLabel: 'SCORM 2004 4E cmi.suspend_data 64000-char',
   interactionFields: {
     responseField: 'learner_response',
     timestampField: 'timestamp',

package/src/runtime/hooks.svelte.ts

@@ -191,6 +191,45 @@ export function useProgress() {
   };
 }
 
+// One dev warning per session, regardless of caller count.
+let warnedNonManualCompletion = false;
+
+/** Test-only: reset the once-per-session warning latch. */
+export function __resetUseCompletionWarning(): void {
+  warnedNonManualCompletion = false;
+}
+
+/**
+ * Trigger course completion from any component, and reactively read the
+ * current completion status. Active under `completion.mode: "manual"`; a
+ * no-op (with a one-shot dev warning) under any other mode.
+ */
+export function useCompletion(): {
+  markComplete(): void;
+  readonly completionStatus: 'incomplete' | 'complete';
+} {
+  const { progress, manifest, config } = requireNavContext('useCompletion()');
+  return {
+    markComplete() {
+      if (config.completion.mode !== 'manual') {
+        if (import.meta.env?.DEV && !warnedNonManualCompletion) {
+          warnedNonManualCompletion = true;
+          console.warn(
+            "Tessera: useCompletion().markComplete() ignored — completion.mode is not 'manual'. " +
+              '(This warning is shown once per session.)'
+          );
+        }
+        return;
+      }
+      progress.markCompleteManually();
+      progress.recalculateSuccess(manifest, config);
+    },
+    get completionStatus() {
+      return progress.completionStatus;
+    },
+  };
+}
+
 /**
  * Scoped persistence — save and restore per-widget state that survives reload.
  * Routes to whichever adapter the course is running under (localStorage, SCORM

package/src/runtime/persistence.ts

@@ -53,4 +53,6 @@ export interface SavedState {
   s?: Record<string, Record<string, number>>;
   /** Graded standalone page indices — pages with at least one graded standalone question */
   gs?: number[];
+  /** Manual completion latch. 1 if the learner triggered manual completion. Absent otherwise. */
+  m?: 1;
 }