tessera-learn 0.2.1 → 0.2.2

package/src/components/Matching.svelte

@@ -3,7 +3,7 @@
   import { SvelteMap } from 'svelte/reactivity';
   import { useQuestion } from '../runtime/hooks.svelte.js';
   import { questionId, shuffle } from './util.js';
-  import LockedBanner from './LockedBanner.svelte';
+  import QuestionShell from './QuestionShell.svelte';
   import ResultIcon from './ResultIcon.svelte';
   import RetryButton from './RetryButton.svelte';
 
@@ -85,10 +85,7 @@
   if (!inQuiz) {
     initShuffle();
   } else {
-    onMount(() => {
-      initShuffle();
-      q.setRender(renderQuestion);
-    });
+    onMount(initShuffle);
   }
 
   function handleLeftClick(leftIndex) {
@@ -166,7 +163,7 @@
   }
 </script>
 
-{#snippet matchingContent()}
+<QuestionShell {q} class="tessera-matching" aria-label={question}>
   <p class="tessera-matching-question">{question}</p>
 
   <div class="tessera-matching-grid">
@@ -268,28 +265,9 @@
       {/if}
     </div>
   {/if}
-{/snippet}
-
-{#if !inQuiz}
-  <div class="tessera-matching" aria-label={question}>
-    {@render matchingContent()}
-  </div>
-{/if}
-
-{#snippet renderQuestion()}
-  <div class="tessera-matching" aria-label={question}>
-    {#if q.isLockedCorrect}
-      <LockedBanner />
-    {/if}
-    {@render matchingContent()}
-  </div>
-{/snippet}
+</QuestionShell>
 
 <style>
-  .tessera-matching {
-    padding: var(--tessera-spacing-md) 0;
-  }
-
   .tessera-matching-question {
     font-size: 1.125rem;
     font-weight: 600;

package/src/components/MultipleChoice.svelte

@@ -1,8 +1,7 @@
 <script>
-  import { onMount } from 'svelte';
   import { useQuestion } from '../runtime/hooks.svelte.js';
   import { questionId } from './util.js';
-  import LockedBanner from './LockedBanner.svelte';
+  import QuestionShell from './QuestionShell.svelte';
   import RetryButton from './RetryButton.svelte';
 
   let {
@@ -45,10 +44,6 @@
   // `q.mode` is fixed for the lifetime of the widget; capture once.
   const inQuiz = q.mode === 'quiz';
 
-  onMount(() => {
-    if (inQuiz) q.setRender(renderQuestion);
-  });
-
   function handleSelect(optIndex) {
     if (q.locked) return;
     selectedOption = optIndex;
@@ -73,7 +68,12 @@
   }
 </script>
 
-{#snippet mcContent()}
+<QuestionShell
+  {q}
+  class="tessera-mc"
+  role="radiogroup"
+  aria-labelledby="{groupId}-label"
+>
   <p class="tessera-mc-question" id="{groupId}-label">{question}</p>
 
   <div class="tessera-mc-options">
@@ -127,28 +127,9 @@
       <RetryButton onclick={() => q.retry()} />
     {/if}
   {/if}
-{/snippet}
-
-{#if !inQuiz}
-  <div class="tessera-mc" role="radiogroup" aria-labelledby="{groupId}-label">
-    {@render mcContent()}
-  </div>
-{/if}
-
-{#snippet renderQuestion()}
-  <div class="tessera-mc" role="radiogroup" aria-labelledby="{groupId}-label">
-    {#if q.isLockedCorrect}
-      <LockedBanner />
-    {/if}
-    {@render mcContent()}
-  </div>
-{/snippet}
+</QuestionShell>
 
 <style>
-  .tessera-mc {
-    padding: var(--tessera-spacing-md) 0;
-  }
-
   .tessera-mc-question {
     font-size: 1.125rem;
     font-weight: 600;

package/src/components/QuestionShell.svelte

@@ -0,0 +1,35 @@
+<script>
+  import { onMount } from 'svelte';
+  import LockedBanner from './LockedBanner.svelte';
+
+  // Shared dual-render wrapper for the question widgets: inline when
+  // standalone, a snippet the Quiz shell renders when inside a quiz.
+  let { q, class: className = '', children, ...rest } = $props();
+
+  const inQuiz = $derived(q.mode === 'quiz');
+
+  onMount(() => {
+    if (inQuiz) q.setRender(quizContent);
+  });
+</script>
+
+{#if !inQuiz}
+  <div class="tessera-question-shell {className}" {...rest}>
+    {@render children?.()}
+  </div>
+{/if}
+
+{#snippet quizContent()}
+  <div class="tessera-question-shell {className}" {...rest}>
+    {#if q.isLockedCorrect}
+      <LockedBanner />
+    {/if}
+    {@render children?.()}
+  </div>
+{/snippet}
+
+<style>
+  .tessera-question-shell {
+    padding: var(--tessera-spacing-md) 0;
+  }
+</style>

package/src/components/Sorting.svelte

@@ -3,7 +3,7 @@
   import { SvelteMap } from 'svelte/reactivity';
   import { useQuestion } from '../runtime/hooks.svelte.js';
   import { questionId, shuffle } from './util.js';
-  import LockedBanner from './LockedBanner.svelte';
+  import QuestionShell from './QuestionShell.svelte';
   import ResultIcon from './ResultIcon.svelte';
   import RetryButton from './RetryButton.svelte';
 
@@ -77,10 +77,7 @@
   if (!inQuiz) {
     initQueue();
   } else {
-    onMount(() => {
-      initQueue();
-      q.setRender(renderQuestion);
-    });
+    onMount(initQueue);
   }
 
   let currentItemIdx = $derived(queue.length > 0 ? queue[0] : null);
@@ -176,7 +173,7 @@
   }
 </script>
 
-{#snippet sortingContent()}
+<QuestionShell {q} class="tessera-sorting" aria-label={question}>
   <p class="tessera-sorting-question">{question}</p>
 
   <!-- Card deck: shows the current card to be placed -->
@@ -321,28 +318,9 @@
       </button>
     </div>
   {/if}
-{/snippet}
-
-{#if !inQuiz}
-  <div class="tessera-sorting" aria-label={question}>
-    {@render sortingContent()}
-  </div>
-{/if}
-
-{#snippet renderQuestion()}
-  <div class="tessera-sorting" aria-label={question}>
-    {#if q.isLockedCorrect}
-      <LockedBanner />
-    {/if}
-    {@render sortingContent()}
-  </div>
-{/snippet}
+</QuestionShell>
 
 <style>
-  .tessera-sorting {
-    padding: var(--tessera-spacing-md) 0;
-  }
-
   .tessera-sorting-question {
     font-size: 1.125rem;
     font-weight: 600;

package/src/plugin/a11y/audit.ts

@@ -1,5 +1,7 @@
-import { existsSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { spawn, type SpawnOptions } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
 import { generateManifest, readCourseConfig } from '../manifest.js';
 import { normalizeA11y, type A11ySettings } from '../validation.js';
 
@@ -23,12 +25,19 @@ const IMPACT_RANK: Record<ImpactLevel, number> = {
 // skips export packaging, and stubs xAPI while it's set. See plugin/index.ts.
 export const AUDIT_ENV_FLAG = 'TESSERA_A11Y_AUDIT';
 
+export interface AxeNodeDetail {
+  target: string;
+  html: string;
+  summary: string;
+}
+
 interface AxeViolation {
   id: string;
   impact: ImpactLevel | null;
   help: string;
   helpUrl: string;
   nodes: number;
+  elements: AxeNodeDetail[];
 }
 
 interface PageAuditResult {
@@ -70,10 +79,210 @@ export function axeIgnoreRules(ignore: string[]): string[] {
   );
 }
 
+const MAX_HTML_LENGTH = 200;
+const MAX_ELEMENTS_SHOWN = 5;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function mapNodeDetail(node: any): AxeNodeDetail {
+  const target = Array.isArray(node?.target)
+    ? node.target.flat(Infinity).join(' ')
+    : String(node?.target ?? '');
+  const html = String(node?.html ?? '');
+  return {
+    target,
+    html:
+      html.length > MAX_HTML_LENGTH
+        ? `${html.slice(0, MAX_HTML_LENGTH - 1)}…`
+        : html,
+    summary: String(node?.failureSummary ?? '')
+      .replace(/\s*\n\s*/g, ' ')
+      .trim(),
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function mapViolation(v: any): AxeViolation {
+  return {
+    id: v.id,
+    impact: v.impact ?? null,
+    help: v.help,
+    helpUrl: v.helpUrl,
+    nodes: v.nodes.length,
+    elements: v.nodes.map(mapNodeDetail),
+  };
+}
+
 export function isMissingBrowserError(message: string): boolean {
   return /Executable doesn't exist|playwright install/i.test(message);
 }
 
+// A missing-deps failure also mentions `playwright install-deps`, so it matches
+// isMissingBrowserError; detect it first to route to the `--with-deps` fix.
+export function isMissingDepsError(message: string): boolean {
+  return /Host system is missing dependencies|missing dependencies to run browser/i.test(
+    message,
+  );
+}
+
+const INSTALL_CHROMIUM = 'pnpm exec playwright install chromium';
+const PLAYWRIGHT_SPECS = ['playwright', '@playwright/test'] as const;
+
+function reportManualInstall(lead: string): void {
+  console.error(
+    `\x1b[31m[tessera a11y]\x1b[0m ${lead}\n` +
+      `  Install it once:\n` +
+      `    ${INSTALL_CHROMIUM}`,
+  );
+}
+
+type SpawnFn = (
+  command: string,
+  args: string[],
+  options: SpawnOptions,
+) => {
+  on(event: 'error', listener: (err: Error) => void): unknown;
+  on(event: 'exit', listener: (code: number | null) => void): unknown;
+  kill?(signal?: NodeJS.Signals): unknown;
+};
+
+function resolvePlaywrightBin():
+  | { command: string; args: string[] }
+  | undefined {
+  const require = createRequire(import.meta.url);
+  for (const spec of PLAYWRIGHT_SPECS) {
+    try {
+      const pkgPath = require.resolve(`${spec}/package.json`);
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as {
+        bin?: string | Record<string, string>;
+      };
+      const binRel =
+        typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.playwright;
+      if (!binRel) continue;
+      return {
+        command: process.execPath,
+        args: [resolve(dirname(pkgPath), binRel), 'install', 'chromium'],
+      };
+    } catch {
+      continue;
+    }
+  }
+  return undefined;
+}
+
+const INSTALL_TIMEOUT_MS = 10 * 60_000;
+
+// Run the workspace's own `playwright` bin with the current Node binary so the
+// install is package-manager-agnostic. No --with-deps: it needs sudo on Linux.
+export async function installChromium(
+  workspaceRoot: string,
+  spawnFn: SpawnFn = spawn,
+  timeoutMs: number = INSTALL_TIMEOUT_MS,
+): Promise<boolean> {
+  const bin = resolvePlaywrightBin();
+  if (!bin) {
+    console.error(
+      `\x1b[31m[tessera a11y]\x1b[0m Could not locate the Playwright CLI to install Chromium.`,
+    );
+    return false;
+  }
+
+  return new Promise<boolean>((resolvePromise) => {
+    const child = spawnFn(bin.command, bin.args, {
+      stdio: 'inherit',
+      cwd: workspaceRoot,
+    });
+    let settled = false;
+    const finish = (ok: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolvePromise(ok);
+    };
+    const timer = setTimeout(() => {
+      console.error(
+        `\x1b[31m[tessera a11y]\x1b[0m Chromium install timed out after ${Math.round(
+          timeoutMs / 60_000,
+        )} min; aborting.`,
+      );
+      child.kill?.('SIGKILL');
+      finish(false);
+    }, timeoutMs);
+    timer.unref?.();
+    child.on('error', (err) => {
+      console.error(
+        `\x1b[31m[tessera a11y]\x1b[0m Failed to start the Chromium install: ${err.message}`,
+      );
+      finish(false);
+    });
+    child.on('exit', (code) => finish(code === 0));
+  });
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type LaunchResult = { ok: true; browser: any } | { ok: false; code: number };
+
+function reportLaunchFailure(message: string, isLinux: boolean): void {
+  console.error(
+    `\x1b[31m[tessera a11y]\x1b[0m Chromium is installed but failed to launch.\n` +
+      (isLinux
+        ? `  Install system dependencies:\n    pnpm exec playwright install --with-deps chromium\n`
+        : ``) +
+      `  Original error: ${message}`,
+  );
+}
+
+// Owns the catch → install → guarded-retry around chromium.launch(). The retry
+// is guarded because a binary-only install can still fail to launch (on Linux,
+// for want of system libs) rather than throw a raw error post-download.
+export async function launchWithInstall({
+  launch,
+  install,
+  isLinux = process.platform === 'linux',
+}: {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  launch: () => Promise<any>;
+  install: () => Promise<boolean>;
+  isLinux?: boolean;
+}): Promise<LaunchResult> {
+  try {
+    return { ok: true, browser: await launch() };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (isMissingDepsError(message)) {
+      reportLaunchFailure(message, isLinux);
+      return { ok: false, code: 1 };
+    }
+    if (!isMissingBrowserError(message)) throw err;
+
+    console.log(
+      "[tessera a11y] Chromium isn't installed for Playwright. Installing it once now…",
+    );
+    const installed = await install();
+    if (!installed) {
+      reportManualInstall("Chromium isn't installed for Playwright.");
+      return { ok: false, code: 1 };
+    }
+
+    try {
+      return { ok: true, browser: await launch() };
+    } catch (retryErr) {
+      const retryMessage =
+        retryErr instanceof Error ? retryErr.message : String(retryErr);
+      if (
+        isMissingBrowserError(retryMessage) &&
+        !isMissingDepsError(retryMessage)
+      ) {
+        reportManualInstall(
+          "Chromium still isn't installed after the install step.",
+        );
+      } else {
+        reportLaunchFailure(retryMessage, isLinux);
+      }
+      return { ok: false, code: 1 };
+    }
+  }
+}
+
 // A violation with no impact is treated as failing rather than slipping the
 // gate at every threshold.
 function isFailing(v: AxeViolation, thresholdRank: number): boolean {
@@ -98,7 +307,7 @@ async function loadDeps(): Promise<
 > {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let chromium: any;
-  for (const spec of ['playwright', '@playwright/test']) {
+  for (const spec of PLAYWRIGHT_SPECS) {
     try {
       const mod = (await tryImport(spec)) as { chromium?: unknown };
       if (mod.chromium) {
@@ -140,7 +349,7 @@ export async function runAudit(
       `\x1b[31m[tessera a11y]\x1b[0m Tier 2 needs Playwright + axe-core, which aren't installed.\n` +
         `  Install them to run the runtime audit:\n` +
         `    pnpm add -D playwright @axe-core/playwright\n` +
-        `    pnpm exec playwright install chromium`,
+        `    ${INSTALL_CHROMIUM}`,
     );
     return 1;
   }
@@ -200,21 +409,12 @@ export async function runAudit(
       return 1;
     }
 
-    let browser;
-    try {
-      browser = await chromium.launch();
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      if (isMissingBrowserError(message)) {
-        console.error(
-          `\x1b[31m[tessera a11y]\x1b[0m Chromium isn't installed for Playwright.\n` +
-            `  Install it once:\n` +
-            `    pnpm exec playwright install chromium`,
-        );
-        return 1;
-      }
-      throw err;
-    }
+    const launched = await launchWithInstall({
+      launch: () => chromium.launch(),
+      install: () => installChromium(workspaceRoot),
+    });
+    if (!launched.ok) return launched.code;
+    const browser = launched.browser;
     const pages: PageAuditResult[] = [];
     try {
       // axe-core/playwright requires a page from an explicit context.
@@ -230,14 +430,7 @@ export async function runAudit(
         const builder = new AxeBuilder({ page }).withTags(tags);
         if (disableRules.length > 0) builder.disableRules(disableRules);
         const out = await builder.analyze();
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        return out.violations.map((v: any) => ({
-          id: v.id,
-          impact: v.impact ?? null,
-          help: v.help,
-          helpUrl: v.helpUrl,
-          nodes: v.nodes.length,
-        }));
+        return out.violations.map(mapViolation);
       };
 
       const recordPage = async (
@@ -351,6 +544,18 @@ function printSummary(report: AuditReport, reportPath: string): void {
       console.log(
         `      [${v.impact ?? 'n/a'}] ${v.id} — ${v.help} (${v.nodes} node${v.nodes === 1 ? '' : 's'})`,
       );
+      for (const el of v.elements.slice(0, MAX_ELEMENTS_SHOWN)) {
+        console.log(
+          `\x1b[90m        → ${el.target || '(unknown element)'}\x1b[0m`,
+        );
+        if (el.summary) console.log(`\x1b[90m          ${el.summary}\x1b[0m`);
+      }
+      const hidden = v.elements.length - MAX_ELEMENTS_SHOWN;
+      if (hidden > 0) {
+        console.log(
+          `\x1b[90m        … and ${hidden} more — see a11y-report.json\x1b[0m`,
+        );
+      }
     }
   }
   console.log(`\n[tessera a11y] Report written to ${reportPath}`);

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/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,
       };
     }