tessera-learn 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tessera-learn",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "LMS tracking runtime for interactive learning content. One adapter layer (SCORM 1.2, SCORM 2004 4th Edition, cmi5, static Web), your choice of components.",
   "keywords": [
     "svelte",
@@ -28,6 +28,9 @@
   "author": "Derek Redmond <derek.redmond@redmondelearning.ca>",
   "license": "MIT",
   "type": "module",
+  "publishConfig": {
+    "provenance": true
+  },
   "files": [
     "dist",
     "src",
@@ -76,8 +79,8 @@
     "acorn": "^8.16.0",
     "archiver": "^8.0.0",
     "json5": "^2.0.0",
-    "svelte": "^5.56.0",
-    "vite": "^8.0.14"
+    "svelte": "^5.56.2",
+    "vite": "^8.0.16"
   },
   "peerDependencies": {
     "@axe-core/playwright": ">=4",
@@ -92,14 +95,14 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
-    "@vitest/coverage-v8": "^4.1.7",
+    "@types/node": "^25.9.2",
+    "@vitest/coverage-v8": "^4.1.8",
     "jsdom": "^29.0.1",
     "scorm-again": "3.0.5",
-    "svelte-check": "^4.4.8",
-    "tsdown": "^0.22.1",
+    "svelte-check": "^4.6.0",
+    "tsdown": "^0.22.2",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.8"
   },
   "scripts": {
     "build": "tsdown",

package/src/components/FillInTheBlank.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 ResultIcon from './ResultIcon.svelte';
   import RetryButton from './RetryButton.svelte';
 
@@ -56,10 +55,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 handleInput(e) {
     if (q.locked) return;
     inputValue = e.target.value;
@@ -79,7 +74,7 @@
   }
 </script>
 
-{#snippet fitbContent()}
+<QuestionShell {q} class="tessera-fitb">
   <label class="tessera-fitb-question" for={inputId}>{question}</label>
 
   <div class="tessera-fitb-input-wrapper">
@@ -138,28 +133,9 @@
       {/if}
     </div>
   {/if}
-{/snippet}
-
-{#if !inQuiz}
-  <div class="tessera-fitb">
-    {@render fitbContent()}
-  </div>
-{/if}
-
-{#snippet renderQuestion()}
-  <div class="tessera-fitb">
-    {#if q.isLockedCorrect}
-      <LockedBanner />
-    {/if}
-    {@render fitbContent()}
-  </div>
-{/snippet}
+</QuestionShell>
 
 <style>
-  .tessera-fitb {
-    padding: var(--tessera-spacing-md) 0;
-  }
-
   .tessera-fitb-question {
     display: block;
     font-size: 1.125rem;

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,13 +1,13 @@
-import { existsSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { spawn, type SpawnOptions } from 'node:child_process';
+import { 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';
 
 export interface AuditOptions {
   /** Minimum violation impact that fails the run (CI gate). Default 'serious'. */
   threshold?: ImpactLevel;
-  /** Force a fresh `vite build` even if dist/ exists. */
-  rebuild?: boolean;
 }
 
 export type ImpactLevel = 'minor' | 'moderate' | 'serious' | 'critical';
@@ -23,12 +23,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 +77,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 +305,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 +347,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;
   }
@@ -169,7 +376,6 @@ export async function runAudit(
 
   // A throwaway web build, kept out of dist/ so a real LMS export is untouched.
   const auditDist = resolve(projectRoot, 'node_modules', '.tessera-a11y');
-  const distHtml = resolve(auditDist, 'index.html');
 
   const prevEnv = process.env[AUDIT_ENV_FLAG];
   process.env[AUDIT_ENV_FLAG] = '1';
@@ -177,15 +383,13 @@ export async function runAudit(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let server: any;
   try {
-    if (options.rebuild || !existsSync(distHtml)) {
-      console.log('[tessera a11y] Building course…');
-      await vite.build(
-        vite.mergeConfig(auditBaseConfig, {
-          build: { outDir: auditDist, emptyOutDir: true },
-          logLevel: 'warn',
-        }),
-      );
-    }
+    console.log('[tessera a11y] Building course…');
+    await vite.build(
+      vite.mergeConfig(auditBaseConfig, {
+        build: { outDir: auditDist, emptyOutDir: true },
+        logLevel: 'warn',
+      }),
+    );
 
     server = await vite.preview({
       root: projectRoot,
@@ -200,21 +404,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 +425,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 +539,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}`);