tessera-learn 0.2.0 → 0.2.2

package/src/plugin/course-root.ts

@@ -32,29 +32,57 @@ export function findWorkspaceRoot(cwd: string): string | null {
   }
 }
 
-export function listCourses(workspaceRoot: string): string[] {
+function scanCourses(workspaceRoot: string): {
+  courses: string[];
+  malformed: string[];
+} {
   const coursesDir = join(workspaceRoot, 'courses');
+  const courses: string[] = [];
+  const malformed: string[] = [];
   try {
-    return readdirSync(coursesDir, { withFileTypes: true })
-      .filter((e) => e.isDirectory() && isCourse(join(coursesDir, e.name)))
-      .map((e) => e.name)
-      .sort();
+    for (const e of readdirSync(coursesDir, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      const dir = join(coursesDir, e.name);
+      if (isCourse(dir)) courses.push(e.name);
+      else if (isDir(join(dir, 'pages'))) malformed.push(e.name);
+    }
   } catch {
-    return [];
+    return { courses, malformed };
   }
+  return { courses: courses.sort(), malformed: malformed.sort() };
+}
+
+export function listCourses(workspaceRoot: string): string[] {
+  return scanCourses(workspaceRoot).courses;
+}
+
+export function listMalformedCourses(workspaceRoot: string): string[] {
+  return scanCourses(workspaceRoot).malformed;
 }
 
 const NOT_A_WORKSPACE =
   'Not inside a Tessera workspace — no `courses/` directory was found at or above the current directory.';
 
+function malformedHint(malformed: string[]): string {
+  if (malformed.length === 0) return '';
+  return (
+    `\nSkipped (missing course.config.js):\n` +
+    malformed.map((c) => `  courses/${c}`).join('\n')
+  );
+}
+
 function listHint(workspaceRoot: string): string {
-  const courses = listCourses(workspaceRoot);
+  const { courses, malformed } = scanCourses(workspaceRoot);
   if (courses.length === 0) {
-    return '\nNo courses found. Create one with `tessera new <name>`.';
+    return (
+      '\nNo courses found. Create one with `tessera new <name>`.' +
+      malformedHint(malformed)
+    );
   }
   return (
     `\nAvailable courses:\n${courses.map((c) => `  ${c}`).join('\n')}` +
-    '\nName one (`tessera <command> <course>`) or cd into its folder.'
+    '\nName one (`tessera <command> <course>`) or cd into its folder.' +
+    malformedHint(malformed)
   );
 }
 

package/src/runtime/App.svelte

@@ -48,6 +48,13 @@
   );
   const nav = new NavigationState(manifest, progress, config, auditMode);
   nav.setPageModules(pageModules);
+
+  // Layout-independent navigation seam the Tier-2 auditor walks pages through.
+  if (auditMode) {
+    window.__tesseraAudit = {
+      goToIndex: (i) => nav.goToPage(i),
+    };
+  }
   let duration = $state(new DurationTracker(0));
 
   const onIdle =
@@ -64,6 +71,9 @@
   let pageLoading = $state(true);
   let pageError = $state(null);
   let retryKey = $state(0);
+  // Rendered page index, surfaced on #tessera-app so the auditor can wait for a
+  // requested navigation to settle before scanning.
+  let renderedPageIndex = $state(-1);
 
   // ---- Page context (reactive, read by Quiz in Step 8) ----
   let pageContext = $state({
@@ -130,6 +140,7 @@
       pageError = new Error(`Page not found: ${page.importPath}`);
       PageComponent = null;
       pageLoading = false;
+      renderedPageIndex = index;
       return;
     }
 
@@ -140,6 +151,7 @@
         pageContext.quiz = page.quiz;
         PageComponent = mod.default;
         pageLoading = false;
+        renderedPageIndex = index;
         progress.markVisited(index);
         if (
           manifest.pages[index].completesOn === 'view' &&
@@ -154,6 +166,7 @@
         console.error(`Tessera: Failed to load page ${index}`, err);
         pageError = err;
         pageLoading = false;
+        renderedPageIndex = index;
       });
   }
 
@@ -446,6 +459,7 @@
   });
 
   onDestroy(() => {
+    if (auditMode) delete window.__tesseraAudit;
     window.removeEventListener('pagehide', handleExit);
     window.removeEventListener('beforeunload', handleExit);
     const appEl = document.getElementById('tessera-app');
@@ -474,7 +488,12 @@
   {/if}
 {/snippet}
 
-<div id="tessera-app" data-chrome={chromeMode}>
+<div
+  id="tessera-app"
+  data-chrome={chromeMode}
+  data-tessera-page-index={auditMode ? renderedPageIndex : undefined}
+  data-tessera-page-error={auditMode && pageError ? 'true' : undefined}
+>
   <LoadingBar active={pageLoading} />
   {#if UserLayout}
     <UserLayout {page} />

package/src/runtime/adapters/cmi5.ts

@@ -579,10 +579,7 @@ export class CMI5Adapter implements PersistenceAdapter {
     opts: { moveOn?: boolean; mastery?: boolean } = {},
   ): Record<string, unknown> {
     const tmpl = this.#launchData?.contextTemplate ?? {};
-    const tmplActivities = (tmpl.contextActivities ?? {}) as Record<
-      string,
-      unknown
-    >;
+    const tmplActivities = tmpl.contextActivities ?? {};
 
     // Concat-dedupe category to preserve any template-supplied entries
     // (§10.2.1 forbids overwriting them).
@@ -594,14 +591,8 @@ export class CMI5Adapter implements PersistenceAdapter {
         category.push({ id, objectType: 'Activity' });
       }
     };
-    const templateCategory = Array.isArray(
-      (tmplActivities as { category?: unknown }).category,
-    )
-      ? (
-          tmplActivities as {
-            category: Array<{ id: string; objectType?: string }>;
-          }
-        ).category
+    const templateCategory = Array.isArray(tmplActivities.category)
+      ? tmplActivities.category
       : [];
     for (const c of templateCategory) {
       if (c && typeof c.id === 'string') push(c.id);
@@ -615,13 +606,13 @@ export class CMI5Adapter implements PersistenceAdapter {
     };
 
     const ctx: Record<string, unknown> = {
-      ...(tmpl as Record<string, unknown>),
+      ...tmpl,
       contextActivities,
     };
     // cmi5 §9.6.3.2 — masteryScore extension is scoped to Passed/Failed.
     if (opts.mastery && this.#masteryScore !== null) {
       ctx.extensions = {
-        ...((tmpl.extensions ?? {}) as Record<string, unknown>),
+        ...(tmpl.extensions ?? {}),
         [CMI5_MASTERYSCORE_EXT]: this.#masteryScore,
       };
     }

package/src/runtime/adapters/index.ts

@@ -19,27 +19,6 @@ export class LMSAdapterError extends Error {
   }
 }
 
-function missingApiError(
-  standard: 'scorm12' | 'scorm2004' | 'cmi5',
-): LMSAdapterError {
-  const label =
-    standard === 'scorm12'
-      ? 'SCORM 1.2'
-      : standard === 'scorm2004'
-        ? 'SCORM 2004'
-        : 'cmi5';
-  const detail =
-    standard === 'cmi5'
-      ? 'No cmi5 launch parameters (fetch / endpoint / activityId / actor) on the URL.'
-      : `No ${label} API object found in the window.parent or window.opener chain.`;
-  return new LMSAdapterError(
-    standard,
-    `Tessera: this course is configured for ${label} but ${detail} ` +
-      `The course must be launched from an LMS that provides the ${label} runtime. ` +
-      `If you are testing locally, run \`npm run dev\` instead, or set export.standard to "web".`,
-  );
-}
-
 export interface CreateAdapterOptions {
   /**
    * When true, a missing LMS API falls back to `WebAdapter` with a console
@@ -49,44 +28,68 @@ export interface CreateAdapterOptions {
   allowFallback?: boolean;
 }
 
-/**
- * Select the appropriate persistence adapter based on course config.
- *
- * In production builds, an LMS-configured course (scorm12/scorm2004/cmi5)
- * will throw `LMSAdapterError` if the matching LMS API isn't reachable —
- * we fail loud so a misconfigured launch is visible immediately rather
- * than silently losing tracking to localStorage.
- *
- * In dev mode, missing APIs warn and fall back to `WebAdapter` so authors
- * can still iterate locally.
- */
 type LMSStandard = 'scorm12' | 'scorm2004' | 'cmi5';
 
-/** Per-standard LMS detection. `detect` returns an adapter when the LMS runtime is reachable, else null. */
+/** Per-standard LMS wiring: `detect` returns an adapter when the LMS runtime is reachable, else null. Labels are the single source for the dev warning and production error. */
 const LMS_ADAPTERS: Record<
   LMSStandard,
-  { detect: () => PersistenceAdapter | null; label: string }
+  {
+    detect: () => PersistenceAdapter | null;
+    warnLabel: string;
+    name: string;
+    missingDetail: string;
+  }
 > = {
   scorm12: {
     detect: () => {
       const api = findSCORM12API();
       return api ? new SCORM12Adapter(api) : null;
     },
-    label: 'SCORM 1.2 API',
+    warnLabel: 'SCORM 1.2 API',
+    name: 'SCORM 1.2',
+    missingDetail:
+      'No SCORM 1.2 API object found in the window.parent or window.opener chain.',
   },
   scorm2004: {
     detect: () => {
       const api = findSCORM2004API();
       return api ? new SCORM2004Adapter(api) : null;
     },
-    label: 'SCORM 2004 API',
+    warnLabel: 'SCORM 2004 API',
+    name: 'SCORM 2004',
+    missingDetail:
+      'No SCORM 2004 API object found in the window.parent or window.opener chain.',
   },
   cmi5: {
     detect: () => (hasCMI5LaunchParams() ? new CMI5Adapter() : null),
-    label: 'cmi5 launch parameters',
+    warnLabel: 'cmi5 launch parameters',
+    name: 'cmi5',
+    missingDetail:
+      'No cmi5 launch parameters (fetch / endpoint / activityId / actor) on the URL.',
   },
 };
 
+function missingApiError(standard: LMSStandard): LMSAdapterError {
+  const { name, missingDetail } = LMS_ADAPTERS[standard];
+  return new LMSAdapterError(
+    standard,
+    `Tessera: this course is configured for ${name} but ${missingDetail} ` +
+      `The course must be launched from an LMS that provides the ${name} runtime. ` +
+      `If you are testing locally, run \`npm run dev\` instead, or set export.standard to "web".`,
+  );
+}
+
+/**
+ * Select the appropriate persistence adapter based on course config.
+ *
+ * In production builds, an LMS-configured course (scorm12/scorm2004/cmi5)
+ * will throw `LMSAdapterError` if the matching LMS API isn't reachable —
+ * we fail loud so a misconfigured launch is visible immediately rather
+ * than silently losing tracking to localStorage.
+ *
+ * In dev mode, missing APIs warn and fall back to `WebAdapter` so authors
+ * can still iterate locally.
+ */
 export function createAdapter(
   config: CourseConfig,
   options: CreateAdapterOptions = {},
@@ -103,7 +106,7 @@ export function createAdapter(
     if (adapter) return adapter;
     if (!allowFallback) throw missingApiError(standard);
     console.warn(
-      `Tessera (dev): ${entry.label} not found — falling back to localStorage`,
+      `Tessera (dev): ${entry.warnLabel} not found — falling back to localStorage`,
     );
   }
   return new WebAdapter(config);

package/src/runtime/adapters/scorm12.ts

@@ -29,7 +29,7 @@ const SCORM12_DIALECT: ScormDialect<SCORM12API> = {
     responseField: 'student_response',
     timestampField: 'time',
     timestamp: () => new Date().toTimeString().slice(0, 8),
-    typeValue: (t) => scorm12Type(t),
+    typeValue: scorm12Type,
     resultLabels: { correct: 'correct', incorrect: 'wrong' },
     format: SCORM12_INTERACTION_FORMAT,
   },

package/src/virtual.d.ts

@@ -30,3 +30,9 @@ interface ImportMetaEnv {
 interface ImportMeta {
   readonly env: ImportMetaEnv;
 }
+
+interface Window {
+  __tesseraAudit?: {
+    goToIndex(index: number): void;
+  };
+}