tessera-learn 0.0.3 → 0.0.5

package/src/plugin/manifest.ts

@@ -13,6 +13,7 @@ export interface ManifestPage {
   slug: string;
   importPath: string;
   quiz: QuizConfig | null;
+  completesOn?: 'view';
 }
 
 export interface ManifestLesson {
@@ -127,7 +128,7 @@ export type PageConfigParseResult =
   /** No module script, or no `pageConfig =` export. Treat as "no config". */
   | { kind: 'none' }
   /** Found and successfully parsed. */
-  | { kind: 'ok'; value: { title?: string; quiz?: QuizConfig } }
+  | { kind: 'ok'; value: { title?: string; quiz?: QuizConfig; completesOn?: 'view' } }
   /** Found but couldn't parse as a static object literal — non-literal RHS or JSON5 failure. */
   | { kind: 'invalid' };
 
@@ -160,7 +161,7 @@ export function parsePageConfigFromSource(content: string): PageConfigParseResul
 }
 
 /** Extract pageConfig from a .svelte file. Throws on parse failure. */
-export function extractPageConfig(filePath: string): { title?: string; quiz?: QuizConfig } {
+export function extractPageConfig(filePath: string): { title?: string; quiz?: QuizConfig; completesOn?: 'view' } {
   const result = parsePageConfigFromSource(readSourceFileCached(filePath));
   if (result.kind === 'ok') return result.value;
   if (result.kind === 'invalid') {
@@ -300,7 +301,7 @@ export function generateManifest(pagesDir: string): Manifest {
         const filePath = resolve(lessonPath, fileName);
         const pageSlug = deriveSlug(fileName, true);
 
-        let pageConfig: { title?: string; quiz?: QuizConfig } = {};
+        let pageConfig: { title?: string; quiz?: QuizConfig; completesOn?: 'view' } = {};
         try {
           pageConfig = extractPageConfig(filePath);
         } catch (e) {
@@ -317,6 +318,7 @@ export function generateManifest(pagesDir: string): Manifest {
           slug: pageSlug,
           importPath: relativePath,
           quiz: pageConfig.quiz || null,
+          ...(pageConfig.completesOn === 'view' ? { completesOn: 'view' as const } : {}),
         };
 
         lesson.pages.push(page);

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);