tessera-learn 0.0.3 → 0.0.5

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

package/src/runtime/progress.svelte.ts

@@ -24,6 +24,21 @@ export class ProgressState {
   completionStatus = $state<'incomplete' | 'complete'>('incomplete');
   successStatus = $state<'unknown' | 'passed' | 'failed'>('unknown');
 
+  // Latch for manual completion. Monotonic; recalc methods bail when set.
+  #manuallyCompleted = $state(false);
+
+  get manuallyCompleted(): boolean {
+    return this.#manuallyCompleted;
+  }
+
+  /** Idempotent — only the first call per session has an effect. */
+  markCompleteManually(): void {
+    if (this.#manuallyCompleted) return;
+    this.#manuallyCompleted = true;
+    this.completionStatus = 'complete';
+    this.version++;
+  }
+
   /**
    * Monotonic counter incremented on every persistable state mutation
    * (visited/scores/chunks/standalone). Callers that need to react to *any*
@@ -100,6 +115,8 @@ export class ProgressState {
   }
 
   recalculateCompletion(manifest: Manifest, config: CourseConfig) {
+    if (this.#manuallyCompleted) return;
+    if (config.completion.mode === 'manual') return;
     if (config.completion.mode === 'percentage') {
       const threshold = config.completion.percentageThreshold ?? 100;
       const percent = manifest.totalPages > 0
@@ -118,6 +135,14 @@ export class ProgressState {
   }
 
   recalculateSuccess(manifest: Manifest, config: CourseConfig) {
+    if (config.completion.mode === 'manual') {
+      const want = config.completion.requireSuccessStatus;
+      // Stay 'unknown' until manual mark fires, so a learner who never
+      // finishes isn't reported as passed.
+      this.successStatus = this.#manuallyCompleted && want !== undefined ? want : 'unknown';
+      return;
+    }
+
     const { indices, attempted } = this.#gradedPages(manifest);
 
     if (indices.length === 0) {

package/src/runtime/types.ts

@@ -29,10 +29,8 @@ export interface CourseConfig {
     mode: 'free' | 'sequential';
     canAccess?: AccessFn;
   };
-  completion: {
-    mode: 'quiz' | 'percentage';
-    percentageThreshold?: number;
-  };
+  completion: ManualCompletion | QuizCompletion | PercentageCompletion;
+  /** Optional under "manual"; required under "quiz". */
   scoring: {
     passingScore: number;
   };
@@ -48,6 +46,27 @@ export interface CourseConfig {
   xapi?: XAPIConfig | XAPIConfig[];
 }
 
+export interface ManualCompletion {
+  mode: 'manual';
+  /**
+   * Set to "page" to opt into a build-time check that at least one page
+   * declares `completesOn: "view"`. Omit to skip the check; both completion
+   * paths still work at runtime.
+   */
+  trigger?: 'page';
+  /** When set, markComplete() also flips successStatus. Omit for unknown. */
+  requireSuccessStatus?: 'passed' | 'failed';
+}
+
+export interface QuizCompletion {
+  mode: 'quiz';
+}
+
+export interface PercentageCompletion {
+  mode: 'percentage';
+  percentageThreshold?: number;
+}
+
 /**
  * cmi5 launch-inherited destination. Only valid under `export.standard:
  * 'cmi5'`. Auth, actor, activityId, and registration are taken from the

package/src/runtime/xapi/publisher.ts

@@ -568,11 +568,30 @@ export class XAPIPublisher {
           })
         );
     }
-    return {
-      ok: false,
-      status: resp.status,
-      error: new Error(`LRS responded ${resp.status}`),
-    };
+    // Append the LRS body to the error message so callers see the
+    // specific reason (e.g. "Forbidden cmi5 defined statement: ...").
+    // Cap at 500 chars; on read failure, fall back to bare status.
+    if (typeof resp.text !== 'function') {
+      return {
+        ok: false,
+        status: resp.status,
+        error: new Error(`LRS responded ${resp.status}`),
+      };
+    }
+    return resp.text().then(
+      (respBody): SendOutcome => ({
+        ok: false,
+        status: resp.status,
+        error: new Error(
+          `LRS responded ${resp.status}${respBody ? `: ${respBody.slice(0, 500)}` : ''}`
+        ),
+      }),
+      (): SendOutcome => ({
+        ok: false,
+        status: resp.status,
+        error: new Error(`LRS responded ${resp.status}`),
+      })
+    );
   }
 
   #resolveAuth(forceRefresh: boolean): Promise<string> {