tessera-learn 0.0.9 → 0.0.11

package/src/components/MultipleChoice.svelte

@@ -58,62 +58,65 @@
 
   function getOptionClass(optIndex) {
     if (!q.feedbackVisible) return '';
-    const answer = inQuiz ? q.answer : selectedOption;
     if (isCorrectOption(optIndex)) return 'correct';
-    if (optIndex === answer && !isCorrectOption(optIndex)) return 'incorrect';
+    if (optIndex === selectedOption && !isCorrectOption(optIndex)) return 'incorrect';
     return '';
   }
 </script>
 
-{#if !inQuiz}
-  <div class="tessera-mc" role="radiogroup" aria-labelledby="{groupId}-label">
-    <p class="tessera-mc-question" id="{groupId}-label">{question}</p>
-
-    <div class="tessera-mc-options">
-      {#each options as option, i}
-        {@const optionId = `${groupId}-opt-${i}`}
-        {@const isSelected = selectedOption === i}
-        {@const stateClass = getOptionClass(i)}
-        <label
-          class="tessera-mc-option {stateClass}"
-          class:selected={isSelected}
-          for={optionId}
-        >
-          <input
-            type="radio"
-            id={optionId}
-            name={groupId}
-            value={i}
-            checked={isSelected}
-            disabled={q.submitted}
-            onchange={() => handleSelect(i)}
-          />
-          <span class="tessera-mc-radio-custom"></span>
-          <span class="tessera-mc-option-text">{option}</span>
-
-          {#if q.submitted}
-            {#if stateClass === 'correct' && (correctFeedback || optionFeedback[i])}
-              <span class="tessera-mc-feedback correct">{optionFeedback[i] || correctFeedback}</span>
-            {:else if stateClass === 'incorrect' && (incorrectFeedback || optionFeedback[i])}
-              <span class="tessera-mc-feedback incorrect">{optionFeedback[i] || incorrectFeedback}</span>
-            {:else if optionFeedback[i]}
-              <span class="tessera-mc-feedback">{optionFeedback[i]}</span>
-            {/if}
+{#snippet mcContent()}
+  <p class="tessera-mc-question" id="{groupId}-label">{question}</p>
+
+  <div class="tessera-mc-options">
+    {#each options as option, i}
+      {@const optionId = `${groupId}-opt-${i}`}
+      {@const isSelected = selectedOption === i}
+      {@const stateClass = getOptionClass(i)}
+      <label
+        class="tessera-mc-option {stateClass}"
+        class:selected={isSelected}
+        for={optionId}
+      >
+        <input
+          type="radio"
+          id={optionId}
+          name={groupId}
+          value={i}
+          checked={isSelected}
+          disabled={q.locked}
+          onchange={() => handleSelect(i)}
+        />
+        <span class="tessera-mc-radio-custom"></span>
+        <span class="tessera-mc-option-text">{option}</span>
+
+        {#if q.feedbackVisible}
+          {#if stateClass === 'correct' && (correctFeedback || optionFeedback[i])}
+            <span class="tessera-mc-feedback correct">{optionFeedback[i] || correctFeedback}</span>
+          {:else if stateClass === 'incorrect' && (incorrectFeedback || optionFeedback[i])}
+            <span class="tessera-mc-feedback incorrect">{optionFeedback[i] || incorrectFeedback}</span>
+          {:else if optionFeedback[i]}
+            <span class="tessera-mc-feedback">{optionFeedback[i]}</span>
           {/if}
-        </label>
-      {/each}
-    </div>
-
-    {#if q.submitted}
-      {#if selectedOption === correct && correctFeedback && !optionFeedback[selectedOption]}
-        <div class="tessera-mc-overall-feedback correct">{correctFeedback}</div>
-      {:else if selectedOption !== correct && incorrectFeedback && !optionFeedback[selectedOption]}
-        <div class="tessera-mc-overall-feedback incorrect">{incorrectFeedback}</div>
-      {/if}
-      {#if q.canRetry}
-        <RetryButton onclick={() => q.retry()} />
-      {/if}
+        {/if}
+      </label>
+    {/each}
+  </div>
+
+  {#if q.feedbackVisible}
+    {#if selectedOption === correct && correctFeedback && !optionFeedback[selectedOption]}
+      <div class="tessera-mc-overall-feedback correct">{correctFeedback}</div>
+    {:else if selectedOption !== correct && incorrectFeedback && !optionFeedback[selectedOption]}
+      <div class="tessera-mc-overall-feedback incorrect">{incorrectFeedback}</div>
+    {/if}
+    {#if !inQuiz && q.canRetry}
+      <RetryButton onclick={() => q.retry()} />
     {/if}
+  {/if}
+{/snippet}
+
+{#if !inQuiz}
+  <div class="tessera-mc" role="radiogroup" aria-labelledby="{groupId}-label">
+    {@render mcContent()}
   </div>
 {/if}
 
@@ -122,51 +125,7 @@
     {#if q.isLockedCorrect}
       <LockedBanner />
     {/if}
-    <p class="tessera-mc-question" id="{groupId}-label">{question}</p>
-
-    <div class="tessera-mc-options">
-      {#each options as option, i}
-        {@const optionId = `${groupId}-opt-${i}`}
-        {@const isSelected = (q.locked ? q.answer : selectedOption) === i}
-        {@const stateClass = getOptionClass(i)}
-        <label
-          class="tessera-mc-option {stateClass}"
-          class:selected={isSelected}
-          for={optionId}
-        >
-          <input
-            type="radio"
-            id={optionId}
-            name={groupId}
-            value={i}
-            checked={isSelected}
-            disabled={q.locked}
-            onchange={() => handleSelect(i)}
-          />
-          <span class="tessera-mc-radio-custom"></span>
-          <span class="tessera-mc-option-text">{option}</span>
-
-          {#if q.feedbackVisible}
-            {#if stateClass === 'correct' && (correctFeedback || optionFeedback[i])}
-              <span class="tessera-mc-feedback correct">{optionFeedback[i] || correctFeedback}</span>
-            {:else if stateClass === 'incorrect' && (incorrectFeedback || optionFeedback[i])}
-              <span class="tessera-mc-feedback incorrect">{optionFeedback[i] || incorrectFeedback}</span>
-            {:else if optionFeedback[i]}
-              <span class="tessera-mc-feedback">{optionFeedback[i]}</span>
-            {/if}
-          {/if}
-        </label>
-      {/each}
-    </div>
-
-    {#if q.feedbackVisible}
-      {@const answer = q.answer}
-      {#if answer === correct && correctFeedback && !optionFeedback[answer]}
-        <div class="tessera-mc-overall-feedback correct">{correctFeedback}</div>
-      {:else if answer !== correct && incorrectFeedback && !optionFeedback[answer]}
-        <div class="tessera-mc-overall-feedback incorrect">{incorrectFeedback}</div>
-      {/if}
-    {/if}
+    {@render mcContent()}
   </div>
 {/snippet}
 

package/src/components/Quiz.svelte

@@ -1,13 +1,14 @@
 <script>
   import { getContext } from 'svelte';
   import { useQuiz } from '../runtime/hooks.svelte.js';
+  import { TESSERA_PAGE } from '../runtime/contexts.js';
 
   let { children } = $props();
   let quizElement = $state(null);
 
   const handle = useQuiz({ element: () => quizElement });
 
-  const pageCtx = getContext('tessera-page');
+  const pageCtx = getContext(TESSERA_PAGE);
   let quizConfig = $derived(pageCtx?.quiz ?? {});
   let feedbackDisabled = $derived(quizConfig.feedbackMode === 'never');
   let maxAttempts = $derived(quizConfig.maxAttempts ?? Infinity);

package/src/components/Video.svelte

@@ -4,12 +4,14 @@
    * 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} src - Video URL (YouTube, Vimeo, direct video file, or $assets/ path)
    * @prop {string} [title] - Accessible label for the video
    */
   import { onMount } from 'svelte';
+  import { resolveAsset } from './util.js';
 
   let { src, title = '' } = $props();
+  let resolvedSrc = $derived(resolveAsset(src));
   let containerRef = $state(null);
   let visible = $state(false);
 
@@ -61,7 +63,7 @@
     {:else}
       <!-- svelte-ignore a11y_media_has_caption -->
       <video controls class="tessera-video-native" aria-label={title}>
-        <source {src} />
+        <source src={resolvedSrc} />
         Your browser does not support the video element.
       </video>
     {/if}

package/src/components/util.ts

@@ -7,6 +7,7 @@
  * same alias semantics.
  */
 export function resolveAsset(src: string): string {
+  if (!src) return src;
   return src.startsWith('$assets/') ? src.replace('$assets/', './assets/') : src;
 }
 

package/src/plugin/cli.ts

@@ -1,15 +1,10 @@
 #!/usr/bin/env node
-import { validateProject } from './validation.js';
+import { validateProject, reportValidationIssues } from './validation.js';
 
 const projectRoot = process.cwd();
 const { errors, warnings } = validateProject(projectRoot);
 
-for (const warning of warnings) {
-  console.warn(`\x1b[33m[tessera warning]\x1b[0m ${warning}`);
-}
-for (const error of errors) {
-  console.error(`\x1b[31m[tessera error]\x1b[0m ${error}`);
-}
+reportValidationIssues({ errors, warnings });
 
 if (errors.length > 0) {
   const summary =

package/src/plugin/export.ts

@@ -228,6 +228,16 @@ function cleanOldZips(projectRoot: string, slug: string): void {
   } catch {}
 }
 
+/** Packaged (zipped) export targets: which manifest file to write and how. */
+const PACKAGED_EXPORTS: Record<
+  'scorm12' | 'scorm2004' | 'cmi5',
+  { manifestFile: string; label: string; generate: (config: ExportConfig, distDir: string) => string }
+> = {
+  scorm12: { manifestFile: 'imsmanifest.xml', label: 'SCORM 1.2', generate: generateSCORM12Manifest },
+  scorm2004: { manifestFile: 'imsmanifest.xml', label: 'SCORM 2004', generate: generateSCORM2004Manifest },
+  cmi5: { manifestFile: 'cmi5.xml', label: 'CMI5', generate: (config) => generateCMI5Xml(config) },
+};
+
 export async function runExport(
   projectRoot: string,
   config: ExportConfig
@@ -239,47 +249,19 @@ export async function runExport(
   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;
-    }
+  if (standard === 'web') {
+    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)})`);
+    return;
+  }
 
-    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;
-    }
+  const spec = PACKAGED_EXPORTS[standard as keyof typeof PACKAGED_EXPORTS];
+  if (!spec) return; // unknown standard — the validator rejects these upstream
 
-    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;
-    }
-  }
+  writeFileSync(resolve(distDir, spec.manifestFile), spec.generate(config, distDir), 'utf-8');
+  cleanOldZips(projectRoot, slug);
+  const zipSize = await createZip(distDir, zipPath);
+  console.log(`✓ ${spec.label} export: ${zipName} (${formatSize(zipSize)})`);
 }

package/src/plugin/index.ts

@@ -2,11 +2,10 @@ import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite';
 import { svelte } from '@sveltejs/vite-plugin-svelte';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, unlinkSync, cpSync, mkdirSync } from 'node:fs';
-import { generateManifest, extractDefaultExportObjectLiteral } from './manifest.js';
-import JSON5 from 'json5';
+import { existsSync, readdirSync, statSync, writeFileSync, unlinkSync, cpSync, mkdirSync } from 'node:fs';
+import { generateManifest, readCourseConfig } from './manifest.js';
 import type { Manifest } from './manifest.js';
-import { validateProject } from './validation.js';
+import { validateProject, reportValidationIssues } from './validation.js';
 import { runExport } from './export.js';
 import { tesseraLayoutPlugin } from './layout.js';
 import { tesseraQuizPlugin } from './quiz.js';
@@ -27,17 +26,21 @@ function resolveStylesDir(): string {
 }
 
 export function tesseraPlugin() {
+  const manifestRef: { current: Manifest | null; root: string } = { current: null, root: '' };
   return [
     svelte({
-      compilerOptions: { css: 'injected' },
+      compilerOptions: { css: 'external' },
     }),
     tesseraValidationPlugin(),
     tesseraEntryPlugin(),
     tesseraConfigPlugin(),
     tesseraPagesPlugin(),
-    tesseraManifestPlugin(),
+    tesseraManifestPlugin(manifestRef),
     tesseraLayoutPlugin(),
     tesseraQuizPlugin(),
+    tesseraAdapterPlugin(),
+    tesseraXAPISetupPlugin(),
+    tesseraFirstPagePreloadPlugin(manifestRef),
     tesseraExportPlugin(),
   ];
 }
@@ -202,6 +205,9 @@ function tesseraConfigPlugin(): Plugin {
 
       return {
         base: './',
+        build: {
+          assetsDir: 'tessera',
+        },
         resolve: {
           alias: {
             '$assets': resolve(root, 'assets'),
@@ -227,15 +233,9 @@ function tesseraConfigPlugin(): Plugin {
     load(id) {
       if (id === RESOLVED_CONFIG_ID) {
         const configPath = resolve(projectRoot, 'course.config.js');
-        let userConfig: Record<string, any> = {};
-
-        if (existsSync(configPath)) {
-          this.addWatchFile(configPath);
-          const objectStr = extractDefaultExportObjectLiteral(readFileSync(configPath, 'utf-8'));
-          if (objectStr) {
-            try { userConfig = JSON5.parse(objectStr); } catch {}
-          }
-        }
+        if (existsSync(configPath)) this.addWatchFile(configPath);
+        const read = readCourseConfig(projectRoot);
+        const userConfig: Record<string, any> = read.ok ? read.config : {};
 
         const { completion, passingScore } = completionDefaults(userConfig.completion?.mode);
         const merged = {
@@ -327,18 +327,11 @@ function tesseraValidationPlugin(): Plugin {
 }
 
 function runValidation(projectRoot: string): void {
-  const { errors, warnings } = validateProject(projectRoot);
-
-  for (const warning of warnings) {
-    console.warn(`\x1b[33m[tessera warning]\x1b[0m ${warning}`);
-  }
-
-  if (errors.length > 0) {
-    for (const error of errors) {
-      console.error(`\x1b[31m[tessera error]\x1b[0m ${error}`);
-    }
+  const result = validateProject(projectRoot);
+  reportValidationIssues(result);
+  if (result.errors.length > 0) {
     throw new Error(
-      `Tessera validation failed with ${errors.length} error(s). Fix the errors above to continue.`
+      `Tessera validation failed with ${result.errors.length} error(s). Fix the errors above to continue.`
     );
   }
 }
@@ -361,33 +354,27 @@ function tesseraExportPlugin(): Plugin {
     async closeBundle() {
       if (!isBuild) return;
 
-      const configPath = resolve(projectRoot, 'course.config.js');
-      if (!existsSync(configPath)) {
-        // Validation already required course.config.js — getting here means
-        // the file vanished mid-build. Surface that loudly rather than
-        // shipping a bundle with no LMS export silently.
-        throw new Error(
-          '[tessera:export] course.config.js not found at closeBundle. The file must exist for the export step to run.'
-        );
-      }
-
-      const objectStr = extractDefaultExportObjectLiteral(readFileSync(configPath, 'utf-8'));
-      if (!objectStr) {
-        throw new Error(
-          '[tessera:export] course.config.js: could not locate `export default { ... }`. Cannot determine export.standard.'
-        );
-      }
-
-      let config: any;
-      try {
-        config = JSON5.parse(objectStr);
-      } catch (err) {
+      const read = readCourseConfig(projectRoot);
+      if (!read.ok) {
+        // Validation already required a parseable course.config.js — getting
+        // here means it vanished or broke mid-build. Surface that loudly
+        // rather than shipping a bundle with no LMS export silently.
+        if (read.reason === 'missing') {
+          throw new Error(
+            '[tessera:export] course.config.js not found at closeBundle. The file must exist for the export step to run.'
+          );
+        }
+        if (read.reason === 'no-export') {
+          throw new Error(
+            '[tessera:export] course.config.js: could not locate `export default { ... }`. Cannot determine export.standard.'
+          );
+        }
         throw new Error(
-          `[tessera:export] course.config.js: failed to parse export-default object literal — ${(err as Error).message}`
+          `[tessera:export] course.config.js: failed to parse export-default object literal — ${(read.error as Error).message}`
         );
       }
 
-      await runExport(projectRoot, config);
+      await runExport(projectRoot, read.config as Parameters<typeof runExport>[1]);
     },
   };
 }
@@ -397,15 +384,15 @@ function tesseraExportPlugin(): Plugin {
 const VIRTUAL_MANIFEST_ID = 'virtual:tessera-manifest';
 const RESOLVED_MANIFEST_ID = '\0' + VIRTUAL_MANIFEST_ID;
 
-function tesseraManifestPlugin(): Plugin {
+function tesseraManifestPlugin(manifestRef: { current: Manifest | null; root: string }): Plugin {
   let projectRoot: string;
   let pagesDir: string;
-  let currentManifest: Manifest | null = null;
   let server: ViteDevServer | null = null;
 
   function buildManifest(): Manifest {
-    currentManifest = generateManifest(pagesDir);
-    return currentManifest;
+    const m = generateManifest(pagesDir);
+    manifestRef.current = m;
+    return m;
   }
 
   return {
@@ -415,6 +402,7 @@ function tesseraManifestPlugin(): Plugin {
     configResolved(config: ResolvedConfig) {
       projectRoot = config.root;
       pagesDir = resolve(projectRoot, 'pages');
+      manifestRef.root = projectRoot;
     },
 
     configureServer(devServer: ViteDevServer) {
@@ -432,7 +420,7 @@ function tesseraManifestPlugin(): Plugin {
           event === 'unlinkDir';
 
         if (isRelevant) {
-          currentManifest = null; // invalidate cache
+          manifestRef.current = null; // invalidate cache
 
           // Invalidate the virtual module to trigger HMR
           const mod = devServer.moduleGraph.getModuleById(RESOLVED_MANIFEST_ID);
@@ -457,7 +445,7 @@ function tesseraManifestPlugin(): Plugin {
 
     load(id) {
       if (id === RESOLVED_MANIFEST_ID) {
-        if (!currentManifest) {
+        if (!manifestRef.current) {
           buildManifest();
         }
 
@@ -468,7 +456,7 @@ function tesseraManifestPlugin(): Plugin {
         // Encode as base64 to prevent Vite's import analysis from
         // scanning .svelte importPath strings as module imports.
         // Replace Infinity with 1e9 since JSON.stringify drops it.
-        const json = JSON.stringify(currentManifest, (_key, value) =>
+        const json = JSON.stringify(manifestRef.current, (_key, value) =>
           value === Infinity ? 1e9 : value
         );
         const b64 = Buffer.from(json).toString('base64');
@@ -478,3 +466,156 @@ function tesseraManifestPlugin(): Plugin {
     },
   };
 }
+
+const VIRTUAL_ADAPTER_ID = 'virtual:tessera-adapter';
+const RESOLVED_ADAPTER_ID = '\0' + VIRTUAL_ADAPTER_ID;
+
+function tesseraAdapterPlugin(): Plugin {
+  let projectRoot: string;
+  let isBuild = false;
+
+  return {
+    name: 'tessera:adapter',
+    enforce: 'pre',
+
+    configResolved(config: ResolvedConfig) {
+      projectRoot = config.root;
+      isBuild = config.command === 'build';
+    },
+
+    resolveId(id) {
+      if (id === VIRTUAL_ADAPTER_ID) return RESOLVED_ADAPTER_ID;
+      return null;
+    },
+
+    load(id) {
+      if (id !== RESOLVED_ADAPTER_ID) return null;
+
+      // In dev, defer to the runtime selector so its WebAdapter fallback
+      // for unreachable LMS APIs keeps working.
+      if (!isBuild) {
+        return `export { createAdapter } from 'tessera-learn/runtime/adapters/index.js';`;
+      }
+
+      let standard = 'web';
+      const read = readCourseConfig(projectRoot);
+      if (read.ok && typeof read.config.export?.standard === 'string') {
+        standard = read.config.export.standard;
+      }
+
+      switch (standard) {
+        case 'scorm12':
+          return `
+import { SCORM12Adapter } from 'tessera-learn/runtime/adapters/scorm12.js';
+import { findSCORM12API } from 'tessera-learn/runtime/adapters/discovery.js';
+import { LMSAdapterError } from 'tessera-learn/runtime/adapters/index.js';
+export function createAdapter() {
+  const api = findSCORM12API();
+  if (!api) throw new LMSAdapterError('scorm12', 'Tessera: SCORM 1.2 API not found in window.parent/opener chain. Course must be launched from a SCORM 1.2 LMS.');
+  return new SCORM12Adapter(api);
+}
+`;
+        case 'scorm2004':
+          return `
+import { SCORM2004Adapter } from 'tessera-learn/runtime/adapters/scorm2004.js';
+import { findSCORM2004API } from 'tessera-learn/runtime/adapters/discovery.js';
+import { LMSAdapterError } from 'tessera-learn/runtime/adapters/index.js';
+export function createAdapter() {
+  const api = findSCORM2004API();
+  if (!api) throw new LMSAdapterError('scorm2004', 'Tessera: SCORM 2004 API not found in window.parent/opener chain. Course must be launched from a SCORM 2004 LMS.');
+  return new SCORM2004Adapter(api);
+}
+`;
+        case 'cmi5':
+          return `
+import { CMI5Adapter } from 'tessera-learn/runtime/adapters/cmi5.js';
+import { hasCMI5LaunchParams } from 'tessera-learn/runtime/adapters/discovery.js';
+import { LMSAdapterError } from 'tessera-learn/runtime/adapters/index.js';
+export function createAdapter() {
+  if (!hasCMI5LaunchParams()) throw new LMSAdapterError('cmi5', 'Tessera: cmi5 launch parameters not present on URL. Course must be launched from a cmi5-compliant LMS.');
+  return new CMI5Adapter();
+}
+`;
+        default:
+          return `
+import { WebAdapter } from 'tessera-learn/runtime/adapters/web.js';
+export function createAdapter(config) {
+  return new WebAdapter(config);
+}
+`;
+      }
+    },
+  };
+}
+
+const VIRTUAL_XAPI_SETUP_ID = 'virtual:tessera-xapi-setup';
+const RESOLVED_XAPI_SETUP_ID = '\0' + VIRTUAL_XAPI_SETUP_ID;
+
+function tesseraXAPISetupPlugin(): Plugin {
+  let projectRoot: string;
+  let isBuild = false;
+
+  return {
+    name: 'tessera:xapi-setup',
+    enforce: 'pre',
+
+    configResolved(config: ResolvedConfig) {
+      projectRoot = config.root;
+      isBuild = config.command === 'build';
+    },
+
+    resolveId(id) {
+      if (id === VIRTUAL_XAPI_SETUP_ID) return RESOLVED_XAPI_SETUP_ID;
+      return null;
+    },
+
+    load(id) {
+      if (id !== RESOLVED_XAPI_SETUP_ID) return null;
+
+      if (!isBuild) {
+        return `export { buildXAPIClient } from 'tessera-learn/runtime/xapi/setup.js';`;
+      }
+
+      let standard = 'web';
+      let hasXapi = false;
+      const read = readCourseConfig(projectRoot);
+      if (read.ok) {
+        if (typeof read.config.export?.standard === 'string') standard = read.config.export.standard;
+        hasXapi = read.config.xapi != null;
+      }
+
+      // cmi5 needs the publisher regardless of explicit xapi config (cmi5
+      // adapter shares the publisher queue for its own LMS-required statements).
+      if (hasXapi || standard === 'cmi5') {
+        return `export { buildXAPIClient } from 'tessera-learn/runtime/xapi/setup.js';`;
+      }
+
+      return `export async function buildXAPIClient() { return null; }`;
+    },
+  };
+}
+
+function tesseraFirstPagePreloadPlugin(manifestRef: { current: Manifest | null; root: string }): Plugin {
+  return {
+    name: 'tessera:first-page-preload',
+    apply: 'build',
+    transformIndexHtml: {
+      order: 'post',
+      handler(_html, ctx) {
+        const firstPagePath = manifestRef.current?.pages[0]?.importPath;
+        if (!firstPagePath || !ctx.bundle) return;
+        const normalized = resolve(manifestRef.root, firstPagePath.replace(/^\//, '')).replace(/\\/g, '/');
+        const chunk = Object.values(ctx.bundle).find(
+          (c): c is import('vite').Rollup.OutputChunk =>
+            c.type === 'chunk' && !!c.facadeModuleId && c.facadeModuleId.replace(/\\/g, '/') === normalized
+        );
+        if (!chunk) return;
+        return [{
+          tag: 'link',
+          attrs: { rel: 'modulepreload', href: `./${chunk.fileName}` },
+          injectTo: 'head',
+        }];
+      },
+    },
+  };
+}