tessera-learn 0.0.1

package/src/runtime/xapi/setup.ts

@@ -0,0 +1,250 @@
+import type { CourseConfig, XAPIConfig, XAPIExplicitConfig } from '../types.js';
+import type { PersistenceAdapter } from '../persistence.js';
+import type { XAPIAgent } from './types.js';
+import { XAPIPublisher } from './publisher.js';
+import { XAPIClient } from './client.js';
+import {
+  synthesizeSCORM12Actor,
+  synthesizeSCORM2004Actor,
+} from './derive-actor.js';
+import { CMI5Adapter } from '../adapters/cmi5.js';
+import { SCORM12Adapter } from '../adapters/scorm12.js';
+import { SCORM2004Adapter } from '../adapters/scorm2004.js';
+
+/**
+ * Wraps a value that the runtime knows how to materialize into an
+ * `XAPIPublisher`. Either a fresh publisher constructed for an explicit
+ * destination, or a reference to the cmi5 adapter's existing publisher
+ * (for the `endpoint: 'lms'` sentinel — same instance, shared queue).
+ */
+type DestinationSource =
+  | { kind: 'lms-shared'; adapter: CMI5Adapter }
+  | { kind: 'explicit'; publisher: XAPIPublisher };
+
+/**
+ * Throws synchronously when `endpoint: 'lms'` appears under cmi5 export
+ * but the runtime was constructed without cmi5 launch parameters (i.e.,
+ * running locally outside an LMS). Surfaced through every
+ * `sendStatement` call rather than silently no-oping — the alternative
+ * produces the "works in dev, silently broken in prod" footgun.
+ */
+class XAPIDevFallbackError extends Error {
+  constructor() {
+    super(
+      "Tessera xAPI: xapi.endpoint is 'lms' but no cmi5 launch parameters " +
+        '(fetch / endpoint / activityId / actor) were present on the URL. ' +
+        'Either launch this course from a real LMS / SCORM Cloud, or ' +
+        "temporarily change xapi.endpoint to an explicit URL pointed at a " +
+        'local LRS (e.g. http://localhost:8080/data/xAPI/) for dev work.'
+    );
+    this.name = 'XAPIDevFallbackError';
+  }
+}
+
+/**
+ * Build a stub publisher whose sends reject with `error`. Used for both
+ * dev-fallback paths: cmi5 `endpoint: 'lms'` with no launch params, and
+ * SCORM explicit endpoints that depend on a learner identity the dev
+ * fallback can't synthesize. The placeholder publisher carries a static
+ * actor so its constructor invariants hold and `XAPIClient.buildStatement`
+ * can run without throwing — only the network-bound methods reject.
+ */
+function makeRejectingPublisher(error: () => Error): XAPIPublisher {
+  const pub = new XAPIPublisher({
+    endpoint: 'http://localhost/__tessera_dev_fallback__/',
+    auth: '',
+    actor: { mbox: 'mailto:nobody@example.invalid', objectType: 'Agent' },
+    activityId: 'http://localhost/__tessera_dev_fallback__',
+  });
+  // The static actor is cached at construction so getActor()/buildStatement
+  // work without a separate init() call. We only override the methods that
+  // would otherwise hit the network so author code surfaces the explicit
+  // error rather than silently no-oping.
+  const reject = (): Promise<never> => Promise.reject(error());
+  (pub as any).sendStatement = reject;
+  (pub as any).enqueueBuilt = reject;
+  return pub;
+}
+
+function makeDevFallbackPublisher(): XAPIPublisher {
+  return makeRejectingPublisher(() => new XAPIDevFallbackError());
+}
+
+class XAPISCORMDevFallbackError extends Error {
+  constructor(standard: 'scorm12' | 'scorm2004') {
+    const label = standard === 'scorm12' ? 'SCORM 1.2' : 'SCORM 2004';
+    super(
+      `Tessera xAPI: ${label} learner identity is unavailable in dev (no LMS API found, ` +
+        'falling back to localStorage). The runtime cannot synthesize an actor for this xapi ' +
+        'destination. Either supply xapi.actor explicitly in course.config.js, or launch from ' +
+        'a real LMS / SCORM Cloud where ' +
+        (standard === 'scorm12' ? 'cmi.core.student_id' : 'cmi.learner_id') +
+        ' is populated.'
+    );
+    this.name = 'XAPISCORMDevFallbackError';
+  }
+}
+
+function makeSCORMDevFallbackPublisher(
+  standard: 'scorm12' | 'scorm2004'
+): XAPIPublisher {
+  return makeRejectingPublisher(() => new XAPISCORMDevFallbackError(standard));
+}
+
+/**
+ * Resolve a single `XAPIConfig` entry into a destination source. Returns
+ * null when the entry can't materialize (e.g., 'lms' with no cmi5
+ * adapter present in non-cmi5 export modes — the validator should have
+ * caught this at build time).
+ */
+function resolveDestination(
+  entry: XAPIConfig,
+  config: CourseConfig,
+  adapter: PersistenceAdapter | null
+): DestinationSource | null {
+  if (entry.endpoint === 'lms') {
+    if (config.export?.standard !== 'cmi5') {
+      // Build-time validator should reject this; defense in depth at runtime.
+      console.warn(
+        "Tessera xAPI: ignoring xapi entry with endpoint: 'lms' under non-cmi5 export."
+      );
+      return null;
+    }
+    if (adapter instanceof CMI5Adapter) {
+      return { kind: 'lms-shared', adapter };
+    }
+    // Dev fallback — cmi5 launch params absent, adapter is the WebAdapter
+    // fallback. Materialize a publisher whose sends reject with an
+    // explicit error so author code surfaces the dev/prod gap.
+    return { kind: 'explicit', publisher: makeDevFallbackPublisher() };
+  }
+
+  // Explicit endpoint.
+  const explicit = entry as XAPIExplicitConfig;
+  const actorOrResolver = resolveExplicitActor(explicit, config, adapter);
+  if (actorOrResolver === null) return null;
+  if (
+    typeof actorOrResolver === 'object' &&
+    (actorOrResolver as { __scormDevFallback?: 'scorm12' | 'scorm2004' })
+      .__scormDevFallback
+  ) {
+    const std = (actorOrResolver as { __scormDevFallback: 'scorm12' | 'scorm2004' })
+      .__scormDevFallback;
+    return { kind: 'explicit', publisher: makeSCORMDevFallbackPublisher(std) };
+  }
+  const publisher = new XAPIPublisher({
+    endpoint: explicit.endpoint,
+    auth: explicit.auth,
+    actor: actorOrResolver as XAPIAgent | (() => XAPIAgent | Promise<XAPIAgent>),
+    activityId: explicit.activityId,
+    registration: explicit.registration,
+  });
+  return { kind: 'explicit', publisher };
+}
+
+/**
+ * Pick an actor (object or resolver function) for an explicit destination,
+ * applying the priority order: author-supplied > cmi5 launch actor >
+ * SCORM-derived actor > error. Returns null if no actor can be resolved
+ * (web export with no `xapi.actor` — build-time validator should have
+ * caught this; runtime returns null and the publisher is skipped).
+ */
+function resolveExplicitActor(
+  explicit: XAPIExplicitConfig,
+  config: CourseConfig,
+  adapter: PersistenceAdapter | null
+):
+  | XAPIAgent
+  | (() => XAPIAgent | Promise<XAPIAgent>)
+  | { __scormDevFallback: 'scorm12' | 'scorm2004' }
+  | null {
+  if (explicit.actor !== undefined) return explicit.actor;
+  // No author-supplied actor — try mode-specific derivation.
+  if (config.export?.standard === 'cmi5' && adapter instanceof CMI5Adapter) {
+    const inner = adapter.getPublisher();
+    if (inner) {
+      // The cmi5 adapter's publisher has the launch actor cached.
+      try {
+        return inner.getActor();
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+  if (config.export?.standard === 'scorm12') {
+    if (adapter instanceof SCORM12Adapter) {
+      return synthesizeSCORM12Actor(
+        adapter.getAPI(),
+        explicit.activityId,
+        explicit.actorAccountHomePage
+      );
+    }
+    // Adapter is the WebAdapter dev fallback. Mirror the cmi5 'lms'
+    // dev-fallback path: install a stub publisher that surfaces an
+    // explicit error rather than silently no-oping. Authors get the
+    // same dev/prod parity in SCORM that they get in cmi5.
+    return { __scormDevFallback: 'scorm12' };
+  }
+  if (config.export?.standard === 'scorm2004') {
+    if (adapter instanceof SCORM2004Adapter) {
+      return synthesizeSCORM2004Actor(
+        adapter.getAPI(),
+        explicit.activityId,
+        explicit.actorAccountHomePage
+      );
+    }
+    return { __scormDevFallback: 'scorm2004' };
+  }
+  // Web export with no actor — build-time validator should have errored.
+  console.warn(
+    'Tessera xAPI: explicit destination has no actor and no derivation source — skipping.'
+  );
+  return null;
+}
+
+/**
+ * Construct an `XAPIClient` from a course's `config.xapi`. Returns null
+ * when xapi is unset, or when no destinations could be resolved.
+ *
+ * The returned client must have `init()` awaited before being registered
+ * so author code calling `useXAPI()` sees a fully initialized client
+ * (in particular, `getActor()` is safe to call sync).
+ */
+export async function buildXAPIClient(
+  config: CourseConfig,
+  adapter: PersistenceAdapter | null
+): Promise<XAPIClient | null> {
+  const raw = config.xapi;
+  if (raw === undefined || raw === null) return null;
+  const entries: XAPIConfig[] = Array.isArray(raw) ? raw : [raw];
+  const sources: DestinationSource[] = [];
+  for (const entry of entries) {
+    const src = resolveDestination(entry, config, adapter);
+    if (src) sources.push(src);
+  }
+  if (sources.length === 0) return null;
+
+  // For each destination, get the publisher (either freshly constructed
+  // for an explicit entry, or the cmi5 adapter's existing instance for
+  // 'lms') and ensure it's initialized.
+  const publishers: XAPIPublisher[] = [];
+  for (const src of sources) {
+    if (src.kind === 'lms-shared') {
+      const inner = src.adapter.getPublisher();
+      if (inner) publishers.push(inner);
+    } else {
+      try {
+        await src.publisher.init();
+        publishers.push(src.publisher);
+      } catch (err) {
+        console.warn(
+          'Tessera xAPI: failed to initialize an explicit destination — skipping.',
+          err
+        );
+      }
+    }
+  }
+  if (publishers.length === 0) return null;
+  return new XAPIClient(publishers);
+}

package/src/runtime/xapi/types.ts

@@ -0,0 +1,106 @@
+/**
+ * xAPI types used by the publisher and registry. These mirror the relevant
+ * subset of the xAPI 1.0.3 spec — the publisher only models Agents (not
+ * Groups) for v1, and only the statement fields actually exercised by
+ * Tessera or surfaced to authors.
+ */
+
+/**
+ * Identified xAPI Agent. Exactly one of `mbox` / `mbox_sha1sum` / `openid` /
+ * `account` must be present (the IFI rule). The publisher validates this on
+ * any actor it resolves; values that fail produce a runtime error rather
+ * than a silent LRS 400.
+ */
+export interface XAPIAgent {
+  name?: string;
+  mbox?: string;
+  mbox_sha1sum?: string;
+  openid?: string;
+  account?: { homePage: string; name: string };
+  objectType?: 'Agent';
+  // Group support is non-goal for v1; field exists so a Group passed by an
+  // author surfaces a friendly validation error instead of a TS mismatch.
+  member?: unknown;
+}
+
+export interface XAPIVerb {
+  id: string;
+  display?: Record<string, string>;
+}
+
+export interface XAPIObject {
+  id: string;
+  objectType?: string;
+  definition?: Record<string, unknown>;
+}
+
+export interface XAPIContext {
+  registration?: string;
+  contextActivities?: {
+    parent?: Array<{ id: string }>;
+    grouping?: Array<{ id: string }>;
+    category?: Array<{ id: string }>;
+    other?: Array<{ id: string }>;
+  };
+  extensions?: Record<string, unknown>;
+}
+
+export interface XAPIResult {
+  success?: boolean;
+  completion?: boolean;
+  duration?: string;
+  score?: { scaled?: number; raw?: number; min?: number; max?: number };
+  response?: string;
+  extensions?: Record<string, unknown>;
+}
+
+/**
+ * Minimal partial-statement shape authors pass to `sendStatement`. The
+ * publisher fills in actor, timestamp, registration, grouping, sessionid
+ * extension, and statement id.
+ */
+export interface PartialStatement {
+  verb: XAPIVerb;
+  object?: XAPIObject;
+  result?: XAPIResult;
+  context?: XAPIContext;
+  attachments?: unknown[];
+}
+
+/**
+ * Fully-formed statement after the publisher has filled in its automatic
+ * fields. Returned in `sendStatement`'s resolved value so authors can log
+ * or assert on what was actually sent.
+ */
+export interface Statement {
+  id: string;
+  actor: XAPIAgent;
+  verb: XAPIVerb;
+  object: XAPIObject;
+  result?: XAPIResult;
+  context?: XAPIContext;
+  timestamp: string;
+  attachments?: unknown[];
+}
+
+export interface DestinationOutcome {
+  endpoint: string;
+  ok: boolean;
+  status?: number;
+  error?: Error;
+}
+
+export interface SendStatementResult {
+  statementId: string;
+  statement: Statement;
+  destinations: DestinationOutcome[];
+}
+
+export interface SendStatementOptions {
+  /**
+   * When false, the publisher sends one attempt and reports the outcome
+   * regardless of failure. Useful for high-volume telemetry where a missing
+   * statement is harmless. Default: true (retry on 5xx/network).
+   */
+  retry?: boolean;
+}

package/src/runtime/xapi/uuid.ts

@@ -0,0 +1,21 @@
+/**
+ * RFC 4122 v4 UUID. Prefer `crypto.randomUUID` (modern browsers, Node 14.17+);
+ * fall back to a getRandomValues-based generator for legacy LMS shells.
+ */
+export function uuidv4(): string {
+  const c: Crypto | undefined = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  const bytes = new Uint8Array(16);
+  if (c?.getRandomValues) c.getRandomValues(bytes);
+  else for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = [...bytes].map((b) => b.toString(16).padStart(2, '0'));
+  return (
+    `${hex.slice(0, 4).join('')}-` +
+    `${hex.slice(4, 6).join('')}-` +
+    `${hex.slice(6, 8).join('')}-` +
+    `${hex.slice(8, 10).join('')}-` +
+    `${hex.slice(10, 16).join('')}`
+  );
+}

package/src/runtime/xapi/validation.ts

@@ -0,0 +1,71 @@
+import type { PartialStatement } from './types.js';
+export { validateAgent, validateAuthCredential } from './agent-rules.js';
+
+/** Thrown for runtime-validation failures (auth/actor resolver misuse). */
+export class XAPIConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'XAPIConfigError';
+  }
+}
+
+/** Thrown synchronously by `sendStatement` for partial-statement misuse. */
+export class XAPIStatementError extends Error {
+  statement: PartialStatement;
+  constructor(message: string, statement: PartialStatement) {
+    super(message);
+    this.name = 'XAPIStatementError';
+    this.statement = statement;
+  }
+}
+
+/**
+ * Validate a partial statement at the boundary. Three checks —
+ * verb.id, object.id when supplied, score.scaled when supplied. Anything
+ * else passes through; the LRS gives clearer errors than we can.
+ *
+ * Called from both the client (so a fan-out send fails once before any
+ * destination's `buildStatement` runs) and the publisher (so a single-
+ * destination caller bypassing the client is still validated).
+ */
+export function validatePartialStatement(partial: PartialStatement): void {
+  if (!partial || typeof partial !== 'object') {
+    throw new XAPIStatementError(
+      'sendStatement: partial statement must be an object',
+      partial
+    );
+  }
+  if (
+    !partial.verb ||
+    typeof partial.verb !== 'object' ||
+    typeof partial.verb.id !== 'string' ||
+    !partial.verb.id
+  ) {
+    throw new XAPIStatementError(
+      'sendStatement: verb.id is required and must be a non-empty string',
+      partial
+    );
+  }
+  if (partial.object !== undefined) {
+    if (
+      !partial.object ||
+      typeof partial.object !== 'object' ||
+      typeof partial.object.id !== 'string' ||
+      !partial.object.id
+    ) {
+      throw new XAPIStatementError(
+        'sendStatement: object.id must be a non-empty string when object is supplied',
+        partial
+      );
+    }
+  }
+  const scaled = partial.result?.score?.scaled;
+  if (scaled !== undefined) {
+    if (typeof scaled !== 'number' || !Number.isFinite(scaled) || scaled < -1 || scaled > 1) {
+      throw new XAPIStatementError(
+        `sendStatement: result.score.scaled must be a number in [-1, 1], got ${scaled}`,
+        partial
+      );
+    }
+  }
+}

package/src/runtime/xapi/version.ts

@@ -0,0 +1,23 @@
+/**
+ * xAPI version negotiated by Tessera. Sent as the `X-Experience-API-Version`
+ * header on every Statement / State API request.
+ *
+ * Pinned to ADL xAPI 1.0.3 — NOT IEEE 9274.1.1 (xAPI 2.0) — because:
+ *
+ *  1. cmi5 v1.0 (the LMS-launch profile we implement) is normatively bound
+ *     to xAPI 1.0.x: §3 / §11 require LRS communication at 1.0.x and the
+ *     `X-Experience-API-Version: 1.0.x` header. A conformant cmi5 LMS will
+ *     reject a `2.0.0` header on its launch endpoint.
+ *  2. ADL has not yet published a cmi5 revision rebased on IEEE 9274. Until
+ *     they do, every cmi5 launch in the wild expects 1.0.x.
+ *  3. None of the 2.0 additions (typed extensions, attachments-by-reference,
+ *     profile registry) are features the runtime exercises — the wire format
+ *     for the statement / state / registration / sessionid extension we use
+ *     is unchanged.
+ *
+ * The right time to bump is when ADL releases cmi5 v2; that work will need
+ * proper version negotiation (the LRS announces its supported versions and
+ * the AU picks the highest mutually-supported one), not just a constant
+ * change here.
+ */
+export const X_API_VERSION = '1.0.3';

package/src/virtual.d.ts

@@ -0,0 +1,16 @@
+declare module 'virtual:tessera-layout' {
+  import type { Component } from 'svelte';
+  const layout: Component<{ page: import('svelte').Snippet }> | null;
+  export default layout;
+}
+
+interface ImportMetaEnv {
+  readonly DEV: boolean;
+  readonly PROD: boolean;
+  readonly MODE: string;
+  readonly SSR: boolean;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/styles/base.css

@@ -0,0 +1,194 @@
+/* ---- Reset ---- */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  -webkit-text-size-adjust: 100%;
+  -moz-tab-size: 4;
+  tab-size: 4;
+  line-height: 1.15;
+}
+
+body {
+  font-family: var(--tessera-font-family);
+  font-size: var(--tessera-font-size-base);
+  line-height: var(--tessera-line-height);
+  color: var(--tessera-text);
+  background-color: var(--tessera-bg);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+button,
+input,
+select,
+textarea {
+  font-family: inherit;
+  font-size: inherit;
+  line-height: inherit;
+  color: inherit;
+}
+
+img,
+svg,
+video,
+canvas,
+audio,
+iframe,
+embed,
+object {
+  display: block;
+  max-width: 100%;
+}
+
+/* ---- Typography ---- */
+h1, h2, h3, h4, h5, h6 {
+  font-weight: 700;
+  line-height: 1.25;
+  color: var(--tessera-text);
+  margin-top: var(--tessera-spacing-xl);
+  margin-bottom: var(--tessera-spacing-md);
+}
+
+h1 { font-size: 2rem; }
+h2 { font-size: 1.625rem; }
+h3 { font-size: 1.375rem; }
+h4 { font-size: 1.125rem; }
+h5 { font-size: 1rem; }
+h6 { font-size: 0.875rem; }
+
+h1:first-child,
+h2:first-child,
+h3:first-child {
+  margin-top: 0;
+}
+
+p {
+  margin-bottom: var(--tessera-spacing-md);
+}
+
+a {
+  color: var(--tessera-primary);
+  text-decoration: underline;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 2px;
+  transition: color var(--tessera-transition-fast);
+}
+
+a:hover {
+  color: var(--tessera-primary-dark);
+}
+
+a:focus-visible {
+  outline: none;
+  box-shadow: var(--tessera-focus-ring);
+  border-radius: 2px;
+}
+
+strong, b {
+  font-weight: 700;
+}
+
+em, i {
+  font-style: italic;
+}
+
+/* ---- Lists ---- */
+ul, ol {
+  margin-bottom: var(--tessera-spacing-md);
+  padding-left: var(--tessera-spacing-xl);
+}
+
+li {
+  margin-bottom: var(--tessera-spacing-sm);
+}
+
+li > ul,
+li > ol {
+  margin-top: var(--tessera-spacing-sm);
+  margin-bottom: 0;
+}
+
+/* ---- Code ---- */
+code {
+  font-family: 'SF Mono', 'Fira Code', 'Fira Mono', Menlo, Consolas, monospace;
+  font-size: 0.875em;
+  background-color: var(--tessera-bg-secondary);
+  border: 1px solid var(--tessera-border);
+  border-radius: 4px;
+  padding: 0.15em 0.4em;
+}
+
+pre {
+  margin-bottom: var(--tessera-spacing-md);
+  padding: var(--tessera-spacing-md);
+  background-color: var(--tessera-bg-secondary);
+  border: 1px solid var(--tessera-border);
+  border-radius: 8px;
+  overflow-x: auto;
+}
+
+pre code {
+  background: none;
+  border: none;
+  padding: 0;
+  font-size: 0.875rem;
+}
+
+/* ---- Blockquote ---- */
+blockquote {
+  margin-bottom: var(--tessera-spacing-md);
+  padding: var(--tessera-spacing-md) var(--tessera-spacing-lg);
+  border-left: 4px solid var(--tessera-primary);
+  background-color: var(--tessera-bg-secondary);
+  border-radius: 0 8px 8px 0;
+  color: var(--tessera-text-light);
+  font-style: italic;
+}
+
+blockquote p:last-child {
+  margin-bottom: 0;
+}
+
+/* ---- Horizontal Rule ---- */
+hr {
+  border: none;
+  border-top: 1px solid var(--tessera-border);
+  margin: var(--tessera-spacing-xl) 0;
+}
+
+/* ---- Table ---- */
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-bottom: var(--tessera-spacing-md);
+  font-size: 0.9375rem;
+}
+
+th, td {
+  padding: var(--tessera-spacing-sm) var(--tessera-spacing-md);
+  border: 1px solid var(--tessera-border);
+  text-align: left;
+}
+
+th {
+  background-color: var(--tessera-bg-secondary);
+  font-weight: 600;
+}
+
+/* ---- Focus Visible ---- */
+:focus-visible {
+  outline: none;
+  box-shadow: var(--tessera-focus-ring);
+}
+
+/* ---- Selection ---- */
+::selection {
+  background-color: var(--tessera-primary-light);
+  color: var(--tessera-text);
+}