tessera-learn 0.0.1

package/src/components/Video.svelte

@@ -0,0 +1,118 @@
+<script>
+  /**
+   * @component Video
+   * Embeds YouTube/Vimeo via iframe or local video files.
+   * Lazy-loads via IntersectionObserver.
+   *
+   * @prop {string} src - Video URL (YouTube, Vimeo, or direct video file)
+   * @prop {string} [title] - Accessible label for the video
+   */
+  import { onMount } from 'svelte';
+
+  let { src, title = '' } = $props();
+  let containerRef = $state(null);
+  let visible = $state(false);
+
+  const youtubeRegex = /(?:youtube\.com\/(?:watch\?v=|embed\/)|youtu\.be\/)([a-zA-Z0-9_-]{11})/;
+  const vimeoRegex = /vimeo\.com\/(?:video\/)?(\d+)/;
+
+  let embedUrl = $derived.by(() => {
+    const ytMatch = src.match(youtubeRegex);
+    if (ytMatch) return `https://www.youtube.com/embed/${ytMatch[1]}`;
+
+    const vimeoMatch = src.match(vimeoRegex);
+    if (vimeoMatch) return `https://player.vimeo.com/video/${vimeoMatch[1]}`;
+
+    return null;
+  });
+
+  let isEmbed = $derived(embedUrl !== null);
+
+  onMount(() => {
+    if (!containerRef) return;
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          visible = true;
+          observer.disconnect();
+        }
+      },
+      { rootMargin: '200px' }
+    );
+
+    observer.observe(containerRef);
+    return () => observer.disconnect();
+  });
+</script>
+
+<div class="tessera-video" bind:this={containerRef} aria-label={title || 'Video'}>
+  {#if visible}
+    {#if isEmbed}
+      <div class="tessera-video-embed">
+        <iframe
+          src={embedUrl}
+          {title}
+          frameborder="0"
+          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+          allowfullscreen
+        ></iframe>
+      </div>
+    {:else}
+      <!-- svelte-ignore a11y_media_has_caption -->
+      <video controls class="tessera-video-native" aria-label={title}>
+        <source {src} />
+        Your browser does not support the video element.
+      </video>
+    {/if}
+  {:else}
+    <div class="tessera-video-placeholder">
+      <span class="tessera-video-placeholder-icon" aria-hidden="true">▶</span>
+    </div>
+  {/if}
+</div>
+
+<style>
+  .tessera-video {
+    margin-bottom: var(--tessera-spacing-lg);
+  }
+
+  .tessera-video-embed {
+    position: relative;
+    padding-bottom: 56.25%; /* 16:9 */
+    height: 0;
+    overflow: hidden;
+    border-radius: 8px;
+  }
+
+  .tessera-video-embed iframe {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    border: none;
+    border-radius: 8px;
+  }
+
+  .tessera-video-native {
+    width: 100%;
+    border-radius: 8px;
+    display: block;
+  }
+
+  .tessera-video-placeholder {
+    aspect-ratio: 16 / 9;
+    background-color: var(--tessera-bg-secondary);
+    border: 1px solid var(--tessera-border);
+    border-radius: 8px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  .tessera-video-placeholder-icon {
+    font-size: 2rem;
+    color: var(--tessera-text-light);
+  }
+</style>

package/src/components/index.ts

@@ -0,0 +1,15 @@
+export { default as Callout } from './Callout.svelte';
+export { default as Image } from './Image.svelte';
+export { default as Accordion } from './Accordion.svelte';
+export { default as AccordionItem } from './AccordionItem.svelte';
+export { default as Carousel } from './Carousel.svelte';
+export { default as CarouselSlide } from './CarouselSlide.svelte';
+export { default as RevealModal } from './RevealModal.svelte';
+export { default as Video } from './Video.svelte';
+export { default as Audio } from './Audio.svelte';
+export { default as Quiz } from './Quiz.svelte';
+export { default as MultipleChoice } from './MultipleChoice.svelte';
+export { default as FillInTheBlank } from './FillInTheBlank.svelte';
+export { default as Matching } from './Matching.svelte';
+export { default as Sorting } from './Sorting.svelte';
+export { default as DefaultLayout } from './DefaultLayout.svelte';

package/src/components/quiz-payload.ts

@@ -0,0 +1,71 @@
+import type { Interaction } from '../runtime/interaction.js';
+
+/**
+ * Shape contributed by a question component when it registers with a `<Quiz>`.
+ * `useQuestion` always supplies both `id` and `interaction`; custom widgets
+ * may omit `interaction` (presentational steps that don't report to the LMS),
+ * in which case they're skipped by `buildQuizInteractions`.
+ */
+export interface QuizQuestionApi {
+  id: string;
+  /** Optional weight for the score rollup. Default 1 — `Σ(w·correct)/Σ(w)*100`. */
+  weight?: number;
+  checkAnswer: (answer: unknown) => boolean;
+  reset?: () => void;
+  render?: unknown;
+  interaction?: () => Interaction;
+}
+
+/**
+ * Reactive context published by `<Quiz>` (and `useQuiz`) under the
+ * `'tessera-quiz'` Svelte context key. Question widgets read this through
+ * `getContext<QuizContext>('tessera-quiz')` to coordinate with their host.
+ *
+ * All accessors are getters so the consumer re-runs when the underlying rune
+ * state changes — destructuring the object will break reactivity.
+ */
+export interface QuizContext {
+  registerQuestion(api: QuizQuestionApi): number;
+  setRender(index: number, render: unknown): void;
+  setAnswer(index: number, answer: unknown): void;
+  getAnswer(index: number): unknown;
+  readonly submitted: boolean;
+  readonly reviewing: boolean;
+  readonly showFeedback: boolean;
+  feedbackVisible(index: number): boolean;
+  isAnswerLocked(index: number): boolean;
+  isLockedCorrect(index: number): boolean;
+}
+
+export interface QuizInteractionEntry {
+  id: string;
+  interaction: Interaction;
+  correct: boolean;
+}
+
+/**
+ * Build the per-question payload included in `tessera-quiz-complete`.
+ *
+ * Skips questions whose `interaction` is missing or returns nullish — custom
+ * widgets may register without an interaction reporter (e.g. presentational
+ * "press to continue" steps), and those simply don't contribute to the
+ * `cmi.interactions` / xAPI Answered stream.
+ */
+export function buildQuizInteractions(
+  questions: QuizQuestionApi[],
+  answers: Map<number, unknown>
+): QuizInteractionEntry[] {
+  const entries: QuizInteractionEntry[] = [];
+  for (let i = 0; i < questions.length; i++) {
+    const q = questions[i];
+    if (typeof q.interaction !== 'function') continue;
+    const interaction = q.interaction();
+    if (!interaction) continue;
+    entries.push({
+      id: q.id,
+      interaction,
+      correct: q.checkAnswer(answers.get(i)),
+    });
+  }
+  return entries;
+}

package/src/components/util.ts

@@ -0,0 +1,24 @@
+/**
+ * Resolve a `$assets/foo` URL to a document-relative path so the asset works
+ * under any deployment root (dev server, static hosts, LMS subpaths, file://).
+ * Pass-through for absolute or external URLs.
+ *
+ * Shared by Image / Audio / Video and any custom component that wants the
+ * same alias semantics.
+ */
+export function resolveAsset(src: string): string {
+  return src.startsWith('$assets/') ? src.replace('$assets/', './assets/') : src;
+}
+
+/**
+ * Build a deterministic slug from a question prompt for use as a fallback
+ * `id` when the author hasn't supplied one. Stable across renders so SCORM /
+ * cmi5 interaction reporting addresses the same question consistently.
+ */
+export function slugFromQuestion(text: unknown): string {
+  return String(text ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40);
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+// ---- Components ----
+// `DefaultLayout` is included via the wildcard re-export.
+export * from './components/index.js';
+
+// ---- Hooks ----
+export {
+  useQuestion,
+  useQuiz,
+  useNavigation,
+  useProgress,
+  usePersistence,
+} from './runtime/hooks.svelte.js';
+
+// ---- Access ----
+export {
+  freeAccess,
+  sequentialAccess,
+  resolveAccess,
+} from './runtime/access.js';
+export type {
+  AccessFn,
+  AccessContext,
+} from './runtime/access.js';
+
+// ---- xAPI ----
+export { useXAPI } from './runtime/xapi/registry.js';
+export type { XAPIClient } from './runtime/xapi/client.js';
+export type {
+  XAPIAgent,
+  XAPIVerb,
+  XAPIObject,
+  XAPIContext,
+  XAPIResult,
+  PartialStatement,
+  Statement,
+  DestinationOutcome,
+  SendStatementResult,
+  SendStatementOptions,
+} from './runtime/xapi/types.js';
+
+// ---- Types ----
+export type {
+  Interaction,
+} from './runtime/interaction.js';
+export { isCorrect } from './runtime/interaction.js';
+export type {
+  UseQuestionOptions,
+  UseQuestionHandle,
+  UseQuizHandle,
+} from './runtime/hooks.svelte.js';
+export type {
+  XAPIConfig,
+  XAPIExplicitConfig,
+  XAPILMSConfig,
+  CourseConfig,
+} from './runtime/types.js';

package/src/plugin/export.ts

@@ -0,0 +1,264 @@
+import { existsSync, readdirSync, statSync, writeFileSync, unlinkSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createWriteStream } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { ZipArchive } from 'archiver';
+import { slugify } from '../runtime/slugify.js';
+
+// ---------- Types ----------
+
+interface ExportConfig {
+  title: string;
+  description?: string;
+  version?: string;
+  scoring?: { passingScore?: number };
+  completion?: { mode?: 'quiz' | 'percentage' };
+  export?: { standard?: string };
+}
+
+// ---------- Helpers ----------
+
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Recursively collect all file paths relative to a directory.
+ */
+function collectFiles(dir: string, base: string = ''): string[] {
+  const files: string[] = [];
+  if (!existsSync(dir)) return files;
+
+  for (const entry of readdirSync(dir)) {
+    const fullPath = resolve(dir, entry);
+    const relPath = base ? `${base}/${entry}` : entry;
+    if (statSync(fullPath).isDirectory()) {
+      files.push(...collectFiles(fullPath, relPath));
+    } else {
+      files.push(relPath);
+    }
+  }
+  return files;
+}
+
+/**
+ * Derive a stable URN IRI from a seed string. cmi5 §13.1 / xs:anyURI
+ * require course / AU ids to be IRIs — bare hex or UUID-shaped strings
+ * (without correct version/variant bits) aren't conformant URNs and may
+ * be rejected by strict LMS importers.
+ *
+ * Hash the seed so the id survives rebuilds, then format as
+ * `urn:tessera:<kind>:<hex>`. The same seed always produces the same
+ * IRI, so existing LRS records are not orphaned by re-export.
+ */
+function stableUrn(kind: 'course' | 'au', seed: string): string {
+  const h = createHash('sha256').update(seed).digest('hex');
+  // 32 hex chars (128 bits of entropy) is plenty; trim to keep ids short.
+  return `urn:tessera:${kind}:${h.slice(0, 32)}`;
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+// ---------- Manifest Generators ----------
+
+export function generateSCORM12Manifest(
+  config: ExportConfig,
+  distDir: string
+): string {
+  const title = escapeXml(config.title || 'Tessera Course');
+  const files = collectFiles(distDir);
+  const fileElements = files
+    .map((f) => `      <file href="${escapeXml(f)}" />`)
+    .join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<manifest identifier="tessera-course" version="1.0"
+  xmlns="http://www.imsproject.org/xsd/imscp_rootv1p1p2"
+  xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_rootv1p2">
+  <metadata>
+    <schema>ADL SCORM</schema>
+    <schemaversion>1.2</schemaversion>
+  </metadata>
+  <organizations default="org-1">
+    <organization identifier="org-1">
+      <title>${title}</title>
+      <item identifier="item-1" identifierref="res-1">
+        <title>${title}</title>
+      </item>
+    </organization>
+  </organizations>
+  <resources>
+    <resource identifier="res-1" type="webcontent" adlcp:scormtype="sco" href="index.html">
+${fileElements}
+    </resource>
+  </resources>
+</manifest>`;
+}
+
+export function generateSCORM2004Manifest(
+  config: ExportConfig,
+  distDir: string
+): string {
+  const title = escapeXml(config.title || 'Tessera Course');
+  const files = collectFiles(distDir);
+  const fileElements = files
+    .map((f) => `      <file href="${escapeXml(f)}" />`)
+    .join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<manifest identifier="tessera-course" version="1.0"
+  xmlns="http://www.imsglobal.org/xsd/imscp_v1p1"
+  xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_v1p3">
+  <metadata>
+    <schema>ADL SCORM</schema>
+    <schemaversion>2004 4th Edition</schemaversion>
+  </metadata>
+  <organizations default="org-1">
+    <organization identifier="org-1">
+      <title>${title}</title>
+      <item identifier="item-1" identifierref="res-1">
+        <title>${title}</title>
+      </item>
+    </organization>
+  </organizations>
+  <resources>
+    <resource identifier="res-1" type="webcontent" adlcp:scormType="sco" href="index.html">
+${fileElements}
+    </resource>
+  </resources>
+</manifest>`;
+}
+
+export function generateCMI5Xml(config: ExportConfig): string {
+  const title = escapeXml(config.title || 'Tessera Course');
+  const description = escapeXml(config.description || '');
+  // Derive stable IDs from the course title so they survive rebuilds without
+  // orphaning existing learner records in the LRS.
+  const courseId = stableUrn('course', `tessera-course:${config.title || ''}`);
+  const auId = stableUrn('au', `tessera-au:${config.title || ''}`);
+  const masteryScore = (config.scoring?.passingScore ?? 70) / 100;
+  // cmi5 §13.1.4 — `moveOn` decides which verb(s) the LMS treats as
+  // satisfying the AU. For graded courses (completion gated on a quiz)
+  // a learner who completes without passing should NOT receive credit, so
+  // the LMS needs both a Completed AND a Passed before satisfaction.
+  // Percentage-mode courses don't surface pass/fail, so completion alone
+  // is the right signal.
+  const moveOn =
+    config.completion?.mode === 'quiz' ? 'CompletedAndPassed' : 'Completed';
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<courseStructure xmlns="https://w3id.org/xapi/profiles/cmi5/v1/CourseStructure.xsd">
+  <course id="${courseId}">
+    <title><langstring lang="en-US">${title}</langstring></title>
+    <description><langstring lang="en-US">${description}</langstring></description>
+  </course>
+  <au id="${auId}" url="index.html" moveOn="${moveOn}" masteryScore="${masteryScore}">
+    <title><langstring lang="en-US">${title}</langstring></title>
+    <description><langstring lang="en-US">${description}</langstring></description>
+  </au>
+</courseStructure>`;
+}
+
+// ---------- ZIP Packaging ----------
+
+export async function createZip(
+  distDir: string,
+  outputPath: string
+): Promise<number> {
+  return new Promise((res, reject) => {
+    const output = createWriteStream(outputPath);
+    const archive = new ZipArchive({ zlib: { level: 9 } });
+
+    output.on('close', () => {
+      res(archive.pointer());
+    });
+    output.on('error', reject);
+    archive.on('error', reject);
+
+    archive.pipe(output);
+    archive.directory(distDir, false);
+    archive.finalize();
+  });
+}
+
+// ---------- Main Export ----------
+
+/**
+ * Run the export process after Vite build completes.
+ * Writes manifest XML into dist/, then packages into ZIP if needed.
+ */
+/** Remove any previously built zips for this package to prevent accumulation. */
+function cleanOldZips(projectRoot: string, slug: string): void {
+  try {
+    for (const f of readdirSync(projectRoot)) {
+      if (f.startsWith(`${slug}-`) && f.endsWith('.zip')) {
+        try { unlinkSync(resolve(projectRoot, f)); } catch {}
+      }
+    }
+  } catch {}
+}
+
+export async function runExport(
+  projectRoot: string,
+  config: ExportConfig
+): Promise<void> {
+  const distDir = resolve(projectRoot, 'dist');
+  const standard = config.export?.standard || 'web';
+  const slug = slugify(config.title || 'tessera-course') || 'tessera-course';
+  const version = config.version || '1.0.0';
+  const zipName = `${slug}-${version}.zip`;
+  const zipPath = resolve(projectRoot, zipName);
+
+  switch (standard) {
+    case 'web': {
+      // Compute dist size
+      const files = collectFiles(distDir);
+      let totalSize = 0;
+      for (const f of files) {
+        totalSize += statSync(resolve(distDir, f)).size;
+      }
+      console.log(`✓ Web export: dist/ (${formatSize(totalSize)})`);
+      break;
+    }
+
+    case 'scorm12': {
+      const manifest = generateSCORM12Manifest(config, distDir);
+      writeFileSync(resolve(distDir, 'imsmanifest.xml'), manifest, 'utf-8');
+      cleanOldZips(projectRoot, slug);
+      const zipSize = await createZip(distDir, zipPath);
+      console.log(
+        `✓ SCORM 1.2 export: ${zipName} (${formatSize(zipSize)})`
+      );
+      break;
+    }
+
+    case 'scorm2004': {
+      const manifest = generateSCORM2004Manifest(config, distDir);
+      writeFileSync(resolve(distDir, 'imsmanifest.xml'), manifest, 'utf-8');
+      cleanOldZips(projectRoot, slug);
+      const zipSize = await createZip(distDir, zipPath);
+      console.log(
+        `✓ SCORM 2004 export: ${zipName} (${formatSize(zipSize)})`
+      );
+      break;
+    }
+
+    case 'cmi5': {
+      const xml = generateCMI5Xml(config);
+      writeFileSync(resolve(distDir, 'cmi5.xml'), xml, 'utf-8');
+      cleanOldZips(projectRoot, slug);
+      const zipSize = await createZip(distDir, zipPath);
+      console.log(`✓ CMI5 export: ${zipName} (${formatSize(zipSize)})`);
+      break;
+    }
+  }
+}