tessera-learn 0.2.0 → 0.2.2

package/README.md

@@ -12,11 +12,11 @@ You probably don't want to install this package directly. Use the scaffolder:
 pnpm create tessera@latest my-course
 ```
 
-That creates a workspace with Tessera wired up, a seed course, and the authoring guide (`AGENTS.md`) at the workspace root. Add more courses with `pnpm tessera new <name>`.
+That creates a workspace with Tessera wired up, a seed course, and a root `AGENTS.md` that points to the authoring guide. Add more courses with `pnpm tessera new <name>`.
 
 ## What's included
 
-- **Hooks** (`tessera-learn`): `useQuestion`, `useQuiz`, `useNavigation`, `useProgress`, `usePersistence`, `useXAPI`.
+- **Hooks** (`tessera-learn`): `useQuestion`, `useQuiz`, `useNavigation`, `useProgress`, `useCompletion`, `usePersistence`, `useXAPI`.
 - **Vite plugin** (`tessera-learn/plugin`): `tesseraPlugin()` — wires page/layout discovery, the LMS adapter, the `$shared` alias, and the export pipeline. The `tessera` CLI (`new`/`dev`/`export`/`validate`/`a11y`/`check`) runs Vite with this plugin for you, so scaffolded workspaces need no `vite.config.js`.
 - **Built-in components** (`tessera-learn`): `Callout`, `Image`, `Audio`, `Video`, `Accordion` / `AccordionItem`, `Carousel` / `CarouselSlide`, `RevealModal`, `Quiz`, `MultipleChoice`, `FillInTheBlank`, `Matching`, `Sorting`, `DefaultLayout`.
 - **LMS adapters**: SCORM 1.2, SCORM 2004 4th Edition, cmi5, static Web — selected via `course.config.js` `export.standard`.
@@ -26,7 +26,7 @@ See `AGENTS.md` for usage, signatures, and authoring conventions.
 
 ## Documentation
 
-The full authoring guide ships with this package at `node_modules/tessera-learn/AGENTS.md`, at the root of any scaffolded project, and on [GitHub](https://github.com/redmodd/tessera/blob/main/AGENTS.md).
+The full authoring guide ships with this package at `node_modules/tessera-learn/AGENTS.md` — scaffolded projects get a small root `AGENTS.md` that points to it — and is on [GitHub](https://github.com/redmodd/tessera/blob/main/packages/tessera-learn/AGENTS.md).
 
 ## License
 

package/dist/{audit-BA5o0ick.js → audit-B9VHgVjk.js}

@@ -1,9 +1,11 @@
+import { createRequire } from "node:module";
 import { basename, dirname, extname, relative, resolve } from "node:path";
 import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import JSON5 from "json5";
 import { Parser } from "acorn";
 import { tsPlugin } from "@sveltejs/acorn-typescript";
 import { parse } from "svelte/compiler";
+import { spawn } from "node:child_process";
 //#region src/plugin/ast.ts
 const rootCache = /* @__PURE__ */ new Map();
 /** Drop every cached root. Call at the start of a run to scope the cache. */
@@ -1385,9 +1387,132 @@ function axeTags(standard) {
 function axeIgnoreRules(ignore) {
 	return ignore.filter((id) => !id.startsWith("tessera/") && !id.startsWith("a11y_"));
 }
+const MAX_HTML_LENGTH = 200;
+const MAX_ELEMENTS_SHOWN = 5;
+function mapNodeDetail(node) {
+	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()
+	};
+}
+function mapViolation(v) {
+	return {
+		id: v.id,
+		impact: v.impact ?? null,
+		help: v.help,
+		helpUrl: v.helpUrl,
+		nodes: v.nodes.length,
+		elements: v.nodes.map(mapNodeDetail)
+	};
+}
 function isMissingBrowserError(message) {
 	return /Executable doesn't exist|playwright install/i.test(message);
 }
+function isMissingDepsError(message) {
+	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"];
+function reportManualInstall(lead) {
+	console.error(`\x1b[31m[tessera a11y]\x1b[0m ${lead}\n  Install it once:\n    ${INSTALL_CHROMIUM}`);
+}
+function resolvePlaywrightBin() {
+	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"));
+		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;
+	}
+}
+const INSTALL_TIMEOUT_MS = 10 * 6e4;
+async function installChromium(workspaceRoot, spawnFn = spawn, timeoutMs = INSTALL_TIMEOUT_MS) {
+	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((resolvePromise) => {
+		const child = spawnFn(bin.command, bin.args, {
+			stdio: "inherit",
+			cwd: workspaceRoot
+		});
+		let settled = false;
+		const finish = (ok) => {
+			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 / 6e4)} 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));
+	});
+}
+function reportLaunchFailure(message, isLinux) {
+	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}`);
+}
+async function launchWithInstall({ launch, install, isLinux = process.platform === "linux" }) {
+	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…");
+		if (!await install()) {
+			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
+			};
+		}
+	}
+}
 function isFailing(v, thresholdRank) {
 	return !v.impact || IMPACT_RANK[v.impact] >= thresholdRank;
 }
@@ -1396,7 +1521,7 @@ async function tryImport(specifier) {
 }
 async function loadDeps() {
 	let chromium;
-	for (const spec of ["playwright", "@playwright/test"]) try {
+	for (const spec of PLAYWRIGHT_SPECS) try {
 		const mod = await tryImport(spec);
 		if (mod.chromium) {
 			chromium = mod.chromium;
@@ -1436,7 +1561,10 @@ async function runAudit(projectRoot, workspaceRoot, options = {}) {
 	const threshold = options.threshold ?? "serious";
 	const deps = await loadDeps();
 	if (!deps.ok) {
-		console.error("\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");
+		console.error(`[tessera a11y] Tier 2 needs Playwright + axe-core, which aren't installed.
+  Install them to run the runtime audit:
+    pnpm add -D playwright @axe-core/playwright
+    ${INSTALL_CHROMIUM}`);
 		return 1;
 	}
 	const { chromium, AxeBuilder } = deps.deps;
@@ -1446,7 +1574,7 @@ async function runAudit(projectRoot, workspaceRoot, options = {}) {
 	const disableRules = axeIgnoreRules(settings.ignore);
 	const manifest = generateManifest(resolve(projectRoot, "pages"));
 	const vite = await import("vite");
-	const { resolveTesseraConfig } = await import("./inline-config-CroQ-_2Y.js");
+	const { resolveTesseraConfig } = await import("./inline-config-eHjv9XuA.js");
 	const auditBaseConfig = await resolveTesseraConfig(projectRoot, workspaceRoot, {
 		command: "build",
 		mode: "production"
@@ -1482,16 +1610,12 @@ async function runAudit(projectRoot, workspaceRoot, options = {}) {
 			console.error("[tessera a11y] Could not determine preview server URL.");
 			return 1;
 		}
-		let browser;
-		try {
-			browser = await chromium.launch();
-		} catch (err) {
-			if (isMissingBrowserError(err instanceof Error ? err.message : String(err))) {
-				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 = [];
 		try {
 			const page = await (await browser.newContext()).newPage();
@@ -1502,31 +1626,31 @@ async function runAudit(projectRoot, workspaceRoot, options = {}) {
 			const scan = async () => {
 				const builder = new AxeBuilder({ page }).withTags(tags);
 				if (disableRules.length > 0) builder.disableRules(disableRules);
-				return (await builder.analyze()).violations.map((v) => ({
-					id: v.id,
-					impact: v.impact ?? null,
-					help: v.help,
-					helpUrl: v.helpUrl,
-					nodes: v.nodes.length
-				}));
+				return (await builder.analyze()).violations.map(mapViolation);
 			};
-			const navCount = await page.locator("button.tessera-nav-page").count();
-			if (navCount === 0) pages.push({
-				index: 0,
-				title: manifest.pages[0]?.title ?? "(entry)",
-				violations: await scan()
-			});
-			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();
-				await page.waitForFunction((idx) => document.querySelectorAll("button.tessera-nav-page")[idx]?.getAttribute("aria-current") === "page", i, { timeout: 2e4 });
-				await page.waitForLoadState("networkidle");
-				pages.push({
-					index: i,
+			const recordPage = async (index, title) => {
+				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 totalPages = manifest.pages.length;
+			if (!await page.evaluate(() => typeof window.__tesseraAudit?.goToIndex === "function")) {
+				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 < totalPages; i++) {
+				await page.evaluate((idx) => window.__tesseraAudit.goToIndex(idx), i);
+				await page.waitForFunction((idx) => document.getElementById("tessera-app")?.dataset.tesseraPageIndex === String(idx), i, { timeout: 2e4 });
+				await page.waitForLoadState("networkidle");
+				pages.push(await recordPage(i, manifest.pages[i]?.title ?? `Page ${i + 1}`));
 			}
 		} finally {
 			await browser.close();
@@ -1534,17 +1658,24 @@ async function runAudit(projectRoot, workspaceRoot, options = {}) {
 		const thresholdRank = IMPACT_RANK[threshold];
 		let totalViolations = 0;
 		let failingViolations = 0;
-		for (const p of pages) for (const v of p.violations) {
-			totalViolations++;
-			if (isFailing(v, thresholdRank)) failingViolations++;
+		let pagesFailedToLoad = 0;
+		for (const p of pages) {
+			if (p.loadFailed) pagesFailedToLoad++;
+			for (const v of p.violations) {
+				totalViolations++;
+				if (isFailing(v, thresholdRank)) failingViolations++;
+			}
 		}
 		const report = {
 			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");
@@ -1562,19 +1693,41 @@ async function runAudit(projectRoot, workspaceRoot, options = {}) {
 function printSummary(report, reportPath) {
 	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;
 		}
 		const mark = p.violations.some((v) => isFailing(v, thresholdRank)) ? "\x1B[31m  ✗\x1B[0m" : "\x1B[33m  ⚠\x1B[0m";
 		console.log(`${mark} ${p.title}`);
-		for (const v of p.violations) console.log(`      [${v.impact ?? "n/a"}] ${v.id} — ${v.help} (${v.nodes} node${v.nodes === 1 ? "" : "s"})`);
+		for (const v of p.violations) {
+			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 console.log(`\x1b[31m[tessera a11y] Failed\x1b[0m — ${report.failingViolations} finding(s) at/above "${report.threshold}" (of ${report.totalViolations} total).`);
+	else {
+		const reasons = [];
+		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 — ${reasons.join("; ")}.`);
+	}
 }
 //#endregion
 export { isPlausibleLanguageTag as a, validateProject as c, isIgnored as i, generateManifest as l, runAudit as n, normalizeA11y as o, resolvePackageRoot as r, reportValidationIssues as s, AUDIT_ENV_FLAG as t, readCourseConfig as u };
 
-//# sourceMappingURL=audit-BA5o0ick.js.map
+//# sourceMappingURL=audit-B9VHgVjk.js.map