tessera-learn 0.0.1

package/src/runtime/quiz-policy.ts

@@ -0,0 +1,227 @@
+/**
+ * Quiz config desugaring. Authors drive feedback / retry / submit-gating /
+ * scoring with either string enums or predicate functions; this module
+ * normalizes both forms into predicates so `useQuiz` only ever interacts
+ * with the predicate API.
+ */
+import type { Interaction } from './interaction.js';
+
+export interface QuizQuestionResult {
+  /** The original interaction reported for the question. */
+  interaction: Interaction;
+  /** Whether this question's response was correct. */
+  correct: boolean;
+  /** Per-question weight from `useQuestion({ weight })`. Defaults to 1. */
+  weight: number;
+}
+
+/**
+ * State the feedback predicate is given so it can decide independently of
+ * the string-enum branches inside `useQuiz`. The predicate is the single
+ * source of truth — the enums (`'immediate'` / `'review'`) desugar into
+ * predicates over this same state.
+ */
+export interface FeedbackVisibilityState {
+  /** Index of the question being asked about. */
+  questionIndex: number;
+  /** Has `submit()` already fired for the current attempt? */
+  submitted: boolean;
+  /** Is the quiz currently in review mode? */
+  reviewing: boolean;
+  /** Has the question been answered (the shell called `setAnswer`)? */
+  hasAnswered: boolean;
+  /**
+   * Has the shell explicitly revealed feedback for this question via
+   * `revealFeedback(index)`? Lets `'immediate'` flows distinguish "answered
+   * but not yet revealed" from "Check Answer button pressed."
+   */
+  revealed: boolean;
+  /** Number of times `submit()` has fired for this quiz instance. */
+  attemptCount: number;
+}
+
+export type FeedbackModePredicate = (state: FeedbackVisibilityState) => boolean;
+export type RetryStrategyPredicate = (results: QuizQuestionResult[]) => Set<number>;
+export type CanSubmitPredicate = (answeredCount: number, totalCount: number) => boolean;
+export type ScorePredicate = (results: QuizQuestionResult[]) => number;
+
+export interface QuizPolicyConfig {
+  /**
+   * Show feedback after each answer (`'immediate'`), only on the review screen
+   * (`'review'`), or via a custom predicate `(state) => boolean` returning
+   * whether feedback should currently be visible. Predicates receive a full
+   * `FeedbackVisibilityState` so they can decide independently of the enum
+   * branches — the enums themselves desugar to predicates over the same state.
+   */
+  feedbackMode?: 'immediate' | 'review' | FeedbackModePredicate;
+  /**
+   * On retry, clear every answer (`'full'`), preserve correct answers
+   * (`'incorrect-only'`), or pass a custom predicate that takes the previous
+   * attempt's results and returns the set of question indices to keep locked.
+   */
+  retryMode?: 'full' | 'incorrect-only' | RetryStrategyPredicate;
+  /**
+   * Custom gate for the Submit button. Defaults to "every registered
+   * question has an answer". Predicates take (answered, total).
+   */
+  canSubmit?: CanSubmitPredicate;
+  /**
+   * Custom score formula. Defaults to weighted-correct percentage —
+   * `Σ(weight × correct) / Σ(weight) × 100`. Authors must return a value in
+   * 0–100; values outside that range warn in dev mode.
+   */
+  score?: ScorePredicate;
+  /**
+   * If false, feedback never renders even when `feedbackMode` says it should.
+   * Mirrors the historical `showFeedback` flag.
+   */
+  showFeedback?: boolean;
+}
+
+/**
+ * Resolve the configured feedback policy into a single predicate that owns
+ * the "should this question's feedback be visible right now?" decision.
+ *
+ * The shipping enums desugar to:
+ *  - `'immediate'` — visible after the shell calls `revealFeedback` for the
+ *    question, OR while the quiz is in review mode.
+ *  - `'review'` (default) — visible only while the quiz is in review mode.
+ *
+ * Predicates receive the full visibility state so they can encode any policy
+ * — e.g. "only after first wrong attempt": `(s) => s.attemptCount > 0 && s.submitted`.
+ *
+ * The `showFeedback: false` global gate is applied separately by `useQuiz`
+ * before this predicate runs.
+ */
+export function resolveFeedbackMode(cfg: QuizPolicyConfig | undefined | null): FeedbackModePredicate {
+  const mode = cfg?.feedbackMode;
+  if (typeof mode === 'function') return mode;
+  if (mode === 'immediate') {
+    return (s) => s.revealed || s.reviewing;
+  }
+  // Default + 'review'
+  return (s) => s.reviewing;
+}
+
+function isDevMode(): boolean {
+  return import.meta.env?.DEV === true;
+}
+
+/**
+ * Resolve the configured retry strategy into a predicate that returns the
+ * set of question indices to lock as "already correct" on the next attempt.
+ *
+ *  - `'full'` (default) — reset everything.
+ *  - `'incorrect-only'` — keep questions the learner got right.
+ *  - function — author decides per result.
+ *
+ * Author predicates are wrapped: a non-Set return turns into "lock nothing"
+ * in production and throws in dev so the bug stays local. An author returning
+ * `[0, 1]` instead of `new Set([0, 1])` would otherwise silently no-op the
+ * lock and quietly break `'incorrect-only'`-style retries.
+ */
+export function resolveRetryStrategy(cfg: QuizPolicyConfig | undefined | null): RetryStrategyPredicate {
+  const mode = cfg?.retryMode;
+  if (typeof mode === 'function') {
+    return (results) => {
+      const raw = mode(results);
+      if (!(raw instanceof Set)) {
+        if (isDevMode()) {
+          throw new TypeError(
+            `[tessera] quiz retryMode predicate returned ${Object.prototype.toString.call(raw)}; ` +
+              `expected a Set<number> of question indices to lock.`
+          );
+        }
+        return new Set<number>();
+      }
+      return raw;
+    };
+  }
+  if (mode === 'incorrect-only') {
+    return (results) => {
+      const locked = new Set<number>();
+      results.forEach((r, i) => {
+        if (r.correct) locked.add(i);
+      });
+      return locked;
+    };
+  }
+  // Default 'full': clear every answer.
+  return () => new Set<number>();
+}
+
+/**
+ * Resolve the Submit gate. Default — all answered.
+ *
+ * Author predicates are wrapped: a non-boolean return is coerced with `!!` in
+ * production and throws in dev. Authors returning `answered` (a number) would
+ * otherwise enable Submit on `0` answered ↔ disable on a count that happens
+ * to equal `NaN` — silently wrong gates either way.
+ */
+export function resolveCanSubmit(cfg: QuizPolicyConfig | undefined | null): CanSubmitPredicate {
+  if (typeof cfg?.canSubmit === 'function') {
+    const fn = cfg.canSubmit;
+    return (answered, total) => {
+      const raw = fn(answered, total);
+      if (typeof raw !== 'boolean') {
+        if (isDevMode()) {
+          throw new TypeError(
+            `[tessera] quiz canSubmit predicate returned ${typeof raw}; expected a boolean.`
+          );
+        }
+        return !!raw;
+      }
+      return raw;
+    };
+  }
+  return (answered, total) => total > 0 && answered >= total;
+}
+
+/**
+ * Resolve the score formula. Default — weighted-correct percentage. With all
+ * weights = 1 (the default for every existing course), the output equals the
+ * pre-Phase-5 unweighted formula.
+ */
+export function resolveScore(cfg: QuizPolicyConfig | undefined | null): ScorePredicate {
+  if (typeof cfg?.score === 'function') {
+    return (results) => {
+      const raw = cfg.score!(results);
+      const isDev = isDevMode();
+      if (typeof raw !== 'number' || !Number.isFinite(raw)) {
+        // NaN/Infinity/non-number can't ride through to setScore(...) — the LMS
+        // either rejects the cmi write or rolls it up to nonsense. Throw in dev
+        // so the bug stays local; clamp to 0 in prod so a runaway predicate
+        // can't crash the learner's session.
+        if (isDev) {
+          throw new TypeError(
+            `[tessera] quiz score predicate returned ${String(raw)}; expected a finite number in 0–100.`
+          );
+        }
+        return 0;
+      }
+      if (raw < 0 || raw > 100) {
+        if (isDev) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[tessera] quiz score predicate returned ${raw}; expected a finite number in 0–100. ` +
+              `Clamping to range — LMSes reject out-of-range cmi.score.raw values.`
+          );
+        }
+        return Math.max(0, Math.min(100, raw));
+      }
+      return raw;
+    };
+  }
+  return (results) => {
+    if (results.length === 0) return 0;
+    let weighted = 0;
+    let totalWeight = 0;
+    for (const r of results) {
+      const w = r.weight > 0 ? r.weight : 1;
+      totalWeight += w;
+      if (r.correct) weighted += w;
+    }
+    if (totalWeight === 0) return 0;
+    return Math.round((weighted / totalWeight) * 100);
+  };
+}

package/src/runtime/slugify.ts

@@ -0,0 +1,17 @@
+/**
+ * Slugify a string for use as a URL-safe / filename-safe identifier.
+ * "My Course Title" → "my-course-title"
+ *
+ * Shared by the runtime (`WebAdapter` localStorage key) and the build-time
+ * exporter (`runExport` zip filename). Both want identical, deterministic
+ * output so a course's storage key matches its package name.
+ */
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}

package/src/runtime/types.ts

@@ -0,0 +1,92 @@
+import type { AccessFn } from './access.js';
+import type { XAPIAgent } from './xapi/types.js';
+
+/**
+ * Per-page quiz configuration. Single source of truth — the build plugin
+ * extracts this from `pageConfig.quiz` and embeds it in the manifest;
+ * the runtime reads it from there. Keep field shapes in sync.
+ */
+export interface QuizConfig {
+  graded?: boolean;
+  gatesProgress?: boolean;
+  maxAttempts?: number;
+  showFeedback?: boolean;
+  feedbackMode?: 'review' | 'immediate';
+  retryMode?: 'full' | 'incorrect-only';
+}
+
+export interface CourseConfig {
+  title: string;
+  description?: string;
+  author?: string;
+  version?: string;
+  branding?: {
+    logo?: string;
+    primaryColor?: string;
+    fontFamily?: string;
+  };
+  navigation: {
+    mode: 'free' | 'sequential';
+    canAccess?: AccessFn;
+  };
+  completion: {
+    mode: 'quiz' | 'percentage';
+    percentageThreshold?: number;
+  };
+  scoring: {
+    passingScore: number;
+  };
+  export: {
+    standard: 'web' | 'scorm12' | 'scorm2004' | 'cmi5';
+  };
+  /**
+   * Optional xAPI destination(s) for custom statement publishing via
+   * `useXAPI()`. A single object or an array of destinations. Under cmi5
+   * export, the sentinel `endpoint: 'lms'` re-uses the LMS launch's
+   * credentials and shares the cmi5 adapter's queue.
+   */
+  xapi?: XAPIConfig | XAPIConfig[];
+}
+
+/**
+ * cmi5 launch-inherited destination. Only valid under `export.standard:
+ * 'cmi5'`. Auth, actor, activityId, and registration are taken from the
+ * launch URL, so no other fields are accepted.
+ */
+export interface XAPILMSConfig {
+  endpoint: 'lms';
+}
+
+/**
+ * Explicit LRS destination. The author provides every field. `actor` is
+ * optional under SCORM (synthesized from `cmi.core.student_id` /
+ * `cmi.learner_id`) and required under web.
+ */
+export interface XAPIExplicitConfig {
+  /** Absolute http(s) URL of the LRS Statements endpoint base. */
+  endpoint: string;
+  /**
+   * Basic-auth credential value (the part after "Basic "), or a function
+   * that resolves one. Function form is re-invoked once on 401 to cover
+   * short-lived tokens.
+   */
+  auth: string | (() => string | Promise<string>);
+  /**
+   * Identified Agent or a resolver function. Required for web export;
+   * optional under SCORM where it can be synthesized from the LMS data
+   * model. Optional under cmi5 where it can be inherited from the launch.
+   */
+  actor?: XAPIAgent | (() => XAPIAgent | Promise<XAPIAgent>);
+  /** xAPI activity IRI scoped to this destination. */
+  activityId: string;
+  /** Optional UUID v4 — primarily a cmi5 launch concept. */
+  registration?: string;
+  /**
+   * Override for the SCORM-derived actor's `account.homePage`. Defaults
+   * to the activityId origin when activityId is http(s); required when
+   * activityId uses a non-http(s) scheme.
+   */
+  actorAccountHomePage?: string;
+}
+
+export type XAPIConfig = XAPILMSConfig | XAPIExplicitConfig;

package/src/runtime/xapi/agent-rules.ts

@@ -0,0 +1,93 @@
+/**
+ * xAPI Identified Agent and Basic-auth credential validation rules.
+ *
+ * Pure logic — no Svelte/runtime imports. Imported by both `publisher.ts`
+ * (runtime validation of resolved actor / auth) and `plugin/validation.ts`
+ * (build-time validation of static `course.config.js` actor / auth).
+ * Keeping the rules in one place prevents the two callsites from drifting.
+ */
+
+/**
+ * Validate that a candidate is an Identified Agent per xAPI 1.0.3.
+ * Returns null on success or a human-readable error suffix on failure.
+ *
+ * Suffixes are prefix-friendly: callers concatenate their own label
+ * (`xapi.actor`, `xapi[0].actor`, etc.) with a single space — no "actor"
+ * appears in the suffix to avoid doubling.
+ */
+export function validateAgent(actor: unknown): string | null {
+  if (!actor || typeof actor !== 'object') {
+    return 'must be an object';
+  }
+  const a = actor as Record<string, unknown>;
+  if (Array.isArray(a.member) && a.member.length > 0) {
+    return 'is a Group (has `member`); v1 supports Identified Agents only';
+  }
+  let count = 0;
+  if (a.mbox !== undefined) count++;
+  if (a.mbox_sha1sum !== undefined) count++;
+  if (a.openid !== undefined) count++;
+  if (a.account !== undefined) count++;
+  if (count === 0) {
+    return 'must have one of mbox, mbox_sha1sum, openid, or account (Identified Agent rule)';
+  }
+  if (count > 1) {
+    return 'must have exactly one IFI (mbox / mbox_sha1sum / openid / account), not multiple';
+  }
+  if (a.mbox !== undefined) {
+    if (typeof a.mbox !== 'string' || !a.mbox.startsWith('mailto:')) {
+      return '.mbox must be a string starting with "mailto:"';
+    }
+  }
+  if (a.mbox_sha1sum !== undefined) {
+    if (typeof a.mbox_sha1sum !== 'string' || !/^[0-9a-f]{40}$/i.test(a.mbox_sha1sum)) {
+      return '.mbox_sha1sum must be a 40-character hex string';
+    }
+  }
+  if (a.openid !== undefined) {
+    if (typeof a.openid !== 'string' || !a.openid) {
+      return '.openid must be a non-empty string';
+    }
+    try {
+      new URL(a.openid);
+    } catch {
+      return '.openid must be an absolute URI';
+    }
+  }
+  if (a.account !== undefined) {
+    const acc = a.account as Record<string, unknown>;
+    if (!acc || typeof acc !== 'object') {
+      return '.account must be an object with homePage and name';
+    }
+    if (typeof acc.homePage !== 'string' || !acc.homePage) {
+      return '.account.homePage must be a non-empty string';
+    }
+    try {
+      new URL(acc.homePage);
+    } catch {
+      return '.account.homePage must be an absolute URL';
+    }
+    if (typeof acc.name !== 'string' || !acc.name) {
+      return '.account.name must be a non-empty string';
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate a Basic-auth credential string (the value after "Basic ").
+ * v1 supports Basic only. Bearer is a hard error so OAuth users see the
+ * non-goal explicitly.
+ */
+export function validateAuthCredential(auth: string): string | null {
+  if (typeof auth !== 'string' || !auth) {
+    return 'auth must be a non-empty string';
+  }
+  if (/^basic\s/i.test(auth)) {
+    return "auth must be the Basic credential value only, not the full header. Drop the 'Basic ' prefix.";
+  }
+  if (/^bearer\s/i.test(auth)) {
+    return 'Bearer/OAuth credentials are not supported in v1. Use Basic auth, or wrap your token-exchange in an auth function that returns a Basic credential.';
+  }
+  return null;
+}

package/src/runtime/xapi/client.ts

@@ -0,0 +1,133 @@
+import type {
+  PartialStatement,
+  SendStatementOptions,
+  SendStatementResult,
+  XAPIAgent,
+  Statement,
+  DestinationOutcome,
+} from './types.js';
+import { XAPIPublisher, XAPIConfigError } from './publisher.js';
+import { validatePartialStatement } from './validation.js';
+import { uuidv4 } from './uuid.js';
+
+/**
+ * What `useXAPI()` returns. Wraps one or more `XAPIPublisher` destinations
+ * and presents a single `sendStatement` API to authors. The single-
+ * destination form (`xapi: { ... }`) and the multi-destination form
+ * (`xapi: [{...}, {...}]`) flow through the same machinery — single is
+ * just a one-element array.
+ *
+ * Each destination has its own queue, auth resolver, and retry loop;
+ * failures are isolated. One UUID is minted per `sendStatement` call and
+ * reused across destinations so analytics keyed on `statement.id` see
+ * identical statements regardless of which LRS they hit first.
+ */
+export class XAPIClient {
+  readonly #publishers: XAPIPublisher[];
+
+  constructor(publishers: XAPIPublisher[]) {
+    if (publishers.length === 0) {
+      throw new Error('XAPIClient: at least one publisher is required');
+    }
+    this.#publishers = publishers;
+  }
+
+  /**
+   * Send a statement to every configured destination. The returned
+   * promise resolves once all destinations have settled (success or
+   * final failure). Per-destination outcomes are exposed on
+   * `result.destinations` so authors can act on partial failures.
+   *
+   * Validation failures throw synchronously — the returned promise
+   * rejects before any HTTP traffic.
+   */
+  sendStatement(
+    partial: PartialStatement,
+    options?: SendStatementOptions
+  ): Promise<SendStatementResult> {
+    try {
+      validatePartialStatement(partial);
+    } catch (err) {
+      return Promise.reject(err);
+    }
+    // cmi5 §9.3.6 — Terminated must be the last statement of the session.
+    // The constraint is per-destination: only cmi5-mode publishers (the
+    // shared-queue cmi5 adapter case) need to block author sends during
+    // unload. Independent explicit-LRS destinations have no such ordering
+    // requirement and stay healthy until the browser tears them down.
+    const blocked = (p: XAPIPublisher) => p.isUnloading() && p.isCmi5Mode();
+    if (this.#publishers.every(blocked)) {
+      return Promise.reject(
+        new XAPIConfigError(
+          'XAPIClient.sendStatement: page is unloading; author statements queued during unload are dropped to keep Terminated last (cmi5 §9.3.6).'
+        )
+      );
+    }
+    const id = uuidv4();
+    // The first publisher's built statement is what we return as the
+    // canonical `statement` in the result. Other destinations may have
+    // a different actor/grouping but the verb/object/result/timestamp
+    // are author-supplied and identical.
+    let primary: Statement | null = null;
+    const destinationPromises: Promise<DestinationOutcome>[] = [];
+    for (let i = 0; i < this.#publishers.length; i++) {
+      const pub = this.#publishers[i];
+      const built = pub.buildStatement(partial, { id });
+      if (i === 0) primary = built;
+      if (blocked(pub)) {
+        destinationPromises.push(
+          Promise.resolve<DestinationOutcome>({
+            endpoint: pub.getEndpoint(),
+            ok: false,
+            error: new XAPIConfigError(
+              'destination skipped: cmi5 publisher is unloading; statement dropped to keep Terminated last (cmi5 §9.3.6).'
+            ),
+          })
+        );
+        continue;
+      }
+      destinationPromises.push(pub.enqueueBuilt(built, options));
+    }
+    return Promise.all(destinationPromises).then((destinations) => ({
+      statementId: id,
+      statement: primary as Statement,
+      destinations,
+    }));
+  }
+
+  /**
+   * Returns the actor of the first destination. For analytics object-id
+   * construction (`${xapi.getActivityId()}#widget-1`) this is what
+   * authors typically want.
+   */
+  getActor(): XAPIAgent {
+    return this.#publishers[0].getActor();
+  }
+
+  /** Returns the activityId of the first destination. */
+  getActivityId(): string {
+    return this.#publishers[0].getActivityId();
+  }
+
+  /** Returns the sessionId of the first destination. */
+  getSessionId(): string {
+    return this.#publishers[0].getSessionId();
+  }
+
+  /** Returns the underlying publishers — mostly useful for tests. */
+  getPublishers(): readonly XAPIPublisher[] {
+    return this.#publishers;
+  }
+
+  /**
+   * Propagate "page is unloading" to every publisher. App.svelte's
+   * pagehide / beforeunload handler calls this before
+   * `adapter.terminate()` so independent (explicit-endpoint) publishers
+   * also stop accepting author sends during the close path. Idempotent;
+   * the cmi5 adapter calls `markUnloading()` on its own publisher
+   * separately and either order is fine.
+   */
+  markUnloading(): void {
+    for (const p of this.#publishers) p.markUnloading();
+  }
+}

package/src/runtime/xapi/derive-actor.ts

@@ -0,0 +1,90 @@
+import type { XAPIAgent } from './types.js';
+import type { SCORM12API } from '../adapters/scorm12.js';
+import type { SCORM2004API } from '../adapters/scorm2004.js';
+
+/**
+ * Compute the default SCORM-derived `account.homePage` from the activity
+ * IRI. Returns the URL origin when `activityId` is an http(s) URL,
+ * otherwise null. Callers that get null and have no `actorAccountHomePage`
+ * override should treat it as a config error (the build-time validator
+ * already enforces this; this is a runtime fallback for completeness).
+ */
+export function defaultAccountHomePage(activityId: string): string | null {
+  try {
+    const url = new URL(activityId);
+    if (url.protocol === 'http:' || url.protocol === 'https:') {
+      return url.origin;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Synthesize an Identified Agent for SCORM 1.2 from the LMS data model.
+ *
+ *   { account: { homePage, name: cmi.core.student_id },
+ *     name: cmi.core.student_name,
+ *     objectType: 'Agent' }
+ *
+ * The `account` IFI satisfies xAPI's Identified Agent rule. `homePage`
+ * defaults to the activityId origin so analytics keyed on actor identity
+ * stay stable across LMS hosts; the author's `actorAccountHomePage`
+ * overrides when the authority namespace is elsewhere.
+ *
+ * Returns null if `student_id` is missing — caller should not construct
+ * a publisher in that case (the LRS would 400 on every send anyway).
+ */
+export function synthesizeSCORM12Actor(
+  api: SCORM12API,
+  activityId: string,
+  actorAccountHomePage?: string
+): XAPIAgent | null {
+  let id = '';
+  let name = '';
+  try {
+    id = api.LMSGetValue('cmi.core.student_id') || '';
+  } catch {}
+  try {
+    name = api.LMSGetValue('cmi.core.student_name') || '';
+  } catch {}
+  if (!id) return null;
+  const homePage = actorAccountHomePage ?? defaultAccountHomePage(activityId);
+  if (!homePage) return null;
+  const agent: XAPIAgent = {
+    account: { homePage, name: id },
+    objectType: 'Agent',
+  };
+  if (name) agent.name = name;
+  return agent;
+}
+
+/**
+ * Synthesize an Identified Agent for SCORM 2004 from the LMS data model.
+ * Same structure as SCORM 1.2 but reads from `cmi.learner_id` /
+ * `cmi.learner_name` (the renamed 2004 fields).
+ */
+export function synthesizeSCORM2004Actor(
+  api: SCORM2004API,
+  activityId: string,
+  actorAccountHomePage?: string
+): XAPIAgent | null {
+  let id = '';
+  let name = '';
+  try {
+    id = api.GetValue('cmi.learner_id') || '';
+  } catch {}
+  try {
+    name = api.GetValue('cmi.learner_name') || '';
+  } catch {}
+  if (!id) return null;
+  const homePage = actorAccountHomePage ?? defaultAccountHomePage(activityId);
+  if (!homePage) return null;
+  const agent: XAPIAgent = {
+    account: { homePage, name: id },
+    objectType: 'Agent',
+  };
+  if (name) agent.name = name;
+  return agent;
+}