tessera-learn 0.2.0 → 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,24 +25,35 @@ 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 {
   index: number;
   title: string;
   violations: AxeViolation[];
+  loadFailed?: boolean;
 }
 
 interface AuditReport {
   standard: A11ySettings['standard'];
   threshold: ImpactLevel;
   pages: PageAuditResult[];
+  pagesAudited: number;
+  totalPages: number;
+  pagesFailedToLoad: number;
   totalViolations: number;
   failingViolations: number;
   passed: boolean;
@@ -66,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 {
@@ -94,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) {
@@ -136,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;
   }
@@ -196,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.
@@ -226,39 +430,54 @@ 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 (
+        index: number,
+        title: string,
+      ): Promise<PageAuditResult> => {
+        const loadFailed = await page.evaluate(
+          () =>
+            document.getElementById('tessera-app')?.dataset.tesseraPageError ===
+            'true',
+        );
+        if (loadFailed) return { index, title, violations: [], loadFailed };
+        return { index, title, violations: await scan() };
       };
 
-      const navCount = await page.locator('button.tessera-nav-page').count();
-      if (navCount === 0) {
-        // No sidebar (custom chrome) — audit whatever is rendered at the entry.
-        pages.push({
-          index: 0,
-          title: manifest.pages[0]?.title ?? '(entry)',
-          violations: await scan(),
-        });
+      const totalPages = manifest.pages.length;
+      const hasAuditHook = await page.evaluate(
+        () => typeof window.__tesseraAudit?.goToIndex === 'function',
+      );
+
+      if (!hasAuditHook) {
+        // No navigation hook — audit the entry only, but flag the reduced scope
+        // rather than passing it off as full coverage.
+        if (totalPages > 1) {
+          console.warn(
+            `\x1b[33m[tessera a11y]\x1b[0m Could not enumerate pages; auditing the entry page only ` +
+              `(1 of ${totalPages}). The report records the reduced scope.`,
+          );
+        }
+        pages.push(await recordPage(0, manifest.pages[0]?.title ?? '(entry)'));
       } else {
-        for (let i = 0; i < navCount; i++) {
-          const btn = page.locator('button.tessera-nav-page').nth(i);
-          const title = (await btn.textContent())?.trim() || `Page ${i + 1}`;
-          await btn.click();
+        for (let i = 0; i < totalPages; i++) {
+          await page.evaluate(
+            (idx: number) => window.__tesseraAudit!.goToIndex(idx),
+            i,
+          );
           await page.waitForFunction(
             (idx: number) =>
-              document
-                .querySelectorAll('button.tessera-nav-page')
-                [idx]?.getAttribute('aria-current') === 'page',
+              document.getElementById('tessera-app')?.dataset
+                .tesseraPageIndex === String(idx),
             i,
             { timeout: 20_000 },
           );
           await page.waitForLoadState('networkidle');
-          pages.push({ index: i, title, violations: await scan() });
+          pages.push(
+            await recordPage(i, manifest.pages[i]?.title ?? `Page ${i + 1}`),
+          );
         }
       }
     } finally {
@@ -268,7 +487,9 @@ export async function runAudit(
     const thresholdRank = IMPACT_RANK[threshold];
     let totalViolations = 0;
     let failingViolations = 0;
+    let pagesFailedToLoad = 0;
     for (const p of pages) {
+      if (p.loadFailed) pagesFailedToLoad++;
       for (const v of p.violations) {
         totalViolations++;
         if (isFailing(v, thresholdRank)) failingViolations++;
@@ -279,9 +500,12 @@ export async function runAudit(
       standard: settings.standard,
       threshold,
       pages,
+      pagesAudited: pages.length,
+      totalPages: manifest.pages.length,
+      pagesFailedToLoad,
       totalViolations,
       failingViolations,
-      passed: failingViolations === 0,
+      passed: failingViolations === 0 && pagesFailedToLoad === 0,
     };
     const reportPath = resolve(projectRoot, 'a11y-report.json');
     writeFileSync(reportPath, JSON.stringify(report, null, 2), 'utf-8');
@@ -305,6 +529,10 @@ export async function runAudit(
 function printSummary(report: AuditReport, reportPath: string): void {
   const thresholdRank = IMPACT_RANK[report.threshold];
   for (const p of report.pages) {
+    if (p.loadFailed) {
+      console.log(`\x1b[31m  ✗\x1b[0m ${p.title} — failed to load`);
+      continue;
+    }
     if (p.violations.length === 0) {
       console.log(`\x1b[32m  ✓\x1b[0m ${p.title}`);
       continue;
@@ -316,16 +544,49 @@ 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}`);
+  if (report.pagesAudited < report.totalPages) {
+    console.log(
+      `\x1b[33m[tessera a11y] Covered ${report.pagesAudited} of ${report.totalPages} page(s)\x1b[0m — reduced scope, the rest were not audited.`,
+    );
+  } else if (report.pagesFailedToLoad > 0) {
+    const scanned = report.pagesAudited - report.pagesFailedToLoad;
+    console.log(
+      `[tessera a11y] Reached all ${report.totalPages} page(s); scanned ${scanned}, ${report.pagesFailedToLoad} failed to load.`,
+    );
+  } else {
+    console.log(`[tessera a11y] Covered all ${report.totalPages} page(s).`);
+  }
   if (report.passed) {
     console.log(
       `\x1b[32m[tessera a11y] Passed\x1b[0m — ${report.totalViolations} total finding(s), none at/above "${report.threshold}".`,
     );
   } else {
+    const reasons: string[] = [];
+    if (report.failingViolations > 0) {
+      reasons.push(
+        `${report.failingViolations} finding(s) at/above "${report.threshold}" (of ${report.totalViolations} total)`,
+      );
+    }
+    if (report.pagesFailedToLoad > 0) {
+      reasons.push(`${report.pagesFailedToLoad} page(s) failed to load`);
+    }
     console.log(
-      `\x1b[31m[tessera a11y] Failed\x1b[0m — ${report.failingViolations} finding(s) at/above "${report.threshold}" (of ${report.totalViolations} total).`,
+      `\x1b[31m[tessera a11y] Failed\x1b[0m — ${reasons.join('; ')}.`,
     );
   }
 }