tessera-learn 0.2.1 → 0.2.3

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-BNrvFHq_.js → audit--fSWIOgK.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,27 +1574,24 @@ 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-Dudu5r8w.js");
+	const { resolveTesseraConfig } = await import("./inline-config-DqAKsCNl.js");
 	const auditBaseConfig = await resolveTesseraConfig(projectRoot, workspaceRoot, {
 		command: "build",
 		mode: "production"
 	});
 	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";
 	let server;
 	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,
 			base: auditBaseConfig.base,
@@ -1482,16 +1607,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,13 +1623,7 @@ 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 recordPage = async (index, title) => {
 				const loadFailed = await page.evaluate(() => document.getElementById("tessera-app")?.dataset.tesseraPageError === "true");
@@ -1585,7 +1700,15 @@ function printSummary(report, reportPath) {
 		}
 		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.`);
@@ -1604,4 +1727,4 @@ function printSummary(report, reportPath) {
 //#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-BNrvFHq_.js.map
+//# sourceMappingURL=audit--fSWIOgK.js.map