tessera-learn 0.1.0 → 0.2.1

package/AGENTS.md

@@ -6,23 +6,73 @@ Build a course with built-in components, your own (via the hooks), or any mix. T
 
 ---
 
+## Workspaces
+
+A Tessera project is a **workspace**: one `package.json` and one `node_modules` shared by **many courses**, plus a `shared/` design system. Each course is a self-contained folder under `courses/`.
+
+```
+my-courses/
+├── package.json            # the one package — owns tessera-learn, svelte, scripts
+├── shared/                 # design system shared across courses (imported as $shared)
+│   ├── Button.svelte
+│   └── tokens.css
+├── courses/
+│   ├── starter-course/     # a course = a content folder (course.config.js, pages/, …)
+│   └── <next course>/
+└── AGENTS.md / CLAUDE.md   # pointers to this guide (workspace root only)
+```
+
+**Everything else in this guide describes a single course** — i.e. the contents of one `courses/<name>/` folder (`course.config.js`, `layout.svelte`, `pages/`, `styles/`).
+
+**Open the workspace folder** (not an individual course) so this guide stays in scope and `$shared` resolves.
+
+### Working with courses
+
+```bash
+pnpm tessera new <name>     # scaffold courses/<name>/ (no install — deps already here)
+pnpm tessera duplicate <source> <new>   # copy an existing course to courses/<new>/
+pnpm tessera dev <name>     # run a command against a named course…
+cd courses/<name> && pnpm exec tessera dev   # …or cd into the course and run it without a name
+pnpm tessera export <name>  # each course exports independently to its own LMS package
+cd courses/<name> && pnpm exec tessera export   # …this works for every command, not just dev
+```
+
+A **bare command at the workspace root errors** and lists the available courses — it never silently picks one, so its meaning can't change as you add courses. Name the course, or `cd` into its folder. (The scaffolded root scripts — `pnpm dev`, `pnpm export`, … — pass straight through, so `pnpm dev <course>` runs that course and a bare `pnpm dev` errors just the same.)
+
+### Sharing across courses with `$shared`
+
+`$shared` resolves to the workspace `shared/` directory, so any course can import the shared design system:
+
+```svelte
+<script>
+  import Button from '$shared/Button.svelte';
+  import '$shared/tokens.css';
+</script>
+
+<Button>Continue</Button>
+```
+
+`$shared` is bundled into each course's export at build time, so it ships in every SCORM/cmi5/web package with no extra wiring.
+
+---
+
 ## Running the project
 
-From the project root (the project is set up for `pnpm` — Node's corepack provisions it automatically):
+From the workspace root (set up for `pnpm` — Node's corepack provisions it automatically). The `dev`/`export`/`validate`/`check` scripts take the course to run; a bare command lists the workspace's courses rather than picking one:
 
 ```bash
 pnpm install              # first time only
-pnpm dev                  # dev server at http://localhost:5173 (Ctrl+C to stop)
-pnpm export               # build + package for the LMS standard configured in course.config.js
-pnpm validate             # run project validation only — no server, no bundle
-pnpm check                # validate, then the runtime accessibility audit (axe) over the built course
+pnpm dev <course>         # dev server at http://localhost:5173 (Ctrl+C to stop)
+pnpm export <course>      # build + package for the LMS standard configured in course.config.js
+pnpm validate <course>    # run project validation only — no server, no bundle
+pnpm check <course>       # validate, then the runtime accessibility audit (axe) over the built course
 ```
 
 The dev server hot-reloads as you edit pages, layouts, components, and `course.config.js`. The `export` command produces a SCORM 1.2, SCORM 2004, cmi5, or static-web bundle depending on `course.config.js`.
 
-`pnpm validate` runs the same checks as `dev` and `export` (page syntax, manifest shape, `pageConfig`, question components, asset references, LMS data-contract bypass, and the static accessibility rules) and exits non-zero if any fail. Use it as a fast feedback loop after editing — it's the quickest way to confirm a change is structurally sound.
+`pnpm validate <course>` runs the same checks as `dev` and `export` (page syntax, manifest shape, `pageConfig`, question components, asset references, LMS data-contract bypass, and the static accessibility rules) and exits non-zero if any fail. Use it as a fast feedback loop after editing — it's the quickest way to confirm a change is structurally sound.
 
-`pnpm check` runs `validate` and then the deeper, opt-in pass (`tessera a11y`): it builds the course, renders every page in a headless browser, and runs [axe-core](https://github.com/dequelabs/axe-core) to catch issues a static scan can't see (computed ARIA, real rendered contrast). The runtime audit drives Playwright, which needs a browser binary once per machine:
+`pnpm check <course>` runs `validate` and then the deeper, opt-in pass (`tessera a11y`): it builds the course, renders every page in a headless browser, and runs [axe-core](https://github.com/dequelabs/axe-core) to catch issues a static scan can't see (computed ARIA, real rendered contrast). The runtime audit drives Playwright, which needs a browser binary once per machine:
 
 ```bash
 pnpm exec playwright install chromium
@@ -842,7 +892,7 @@ export default {
 
 ### Build output
 
-`pnpm export` (which wraps `vite build`) writes:
+`pnpm export <course>` (which wraps `vite build`) writes:
 
 | `export.standard` | What ships                            | Where                                    |
 | ----------------- | ------------------------------------- | ---------------------------------------- |
@@ -855,7 +905,7 @@ For LMS exports, upload the zip via your LMS's import flow. For web export, the
 
 ### Validation
 
-The Vite plugin runs project validation on every dev start and build (page syntax, manifest shape, `pageConfig` parseability, question components, asset references, LMS data-contract bypass, etc.). Errors abort the build and print as `[tessera error] ...`; warnings print as `[tessera warning] ...` and don't block. Run `pnpm validate` to check without building.
+The Vite plugin runs project validation on every dev start and build (page syntax, manifest shape, `pageConfig` parseability, question components, asset references, LMS data-contract bypass, etc.). Errors abort the build and print as `[tessera error] ...`; warnings print as `[tessera warning] ...` and don't block. Run `pnpm validate <course>` to check without building.
 
 ---
 
@@ -865,7 +915,7 @@ Tessera checks accessibility in two passes, plus components that are accessible
 
 **Static checks** run inside `validate`, `dev`, and `export` — no extra setup. They cover what's visible in your source: `<Image>` alt-or-`decorative`, `<Video>`/`<Audio>` `title` + captions/transcript, empty question option/answer labels, skipped heading levels (e.g. `h2` → `h4`), `branding.primaryColor` contrast against white, and a well-formed `language` tag. They also route the Svelte compiler's own `a11y_*` warnings through the reporter. Each diagnostic carries a rule ID in brackets (e.g. `[tessera/image-alt]`, `[a11y_missing_attribute]`) — that ID is what `a11y.ignore` and `a11y.level` match.
 
-**Runtime audit** is the opt-in deep pass: `tessera a11y` (run it directly, or via `pnpm check`, which runs `validate` first) builds the course, renders **every** page in a headless browser (including pages gated behind a quiz), runs [axe-core](https://github.com/dequelabs/axe-core), writes `a11y-report.json`, and exits non-zero on any violation at or above an impact threshold (default `serious`). It catches what a static scan can't — computed ARIA, focus order, real rendered contrast.
+**Runtime audit** is the opt-in deep pass: `pnpm a11y <course>` (run it directly, or via `pnpm check <course>`, which runs `validate` first) builds the course, renders **every** page in a headless browser (including pages gated behind a quiz), runs [axe-core](https://github.com/dequelabs/axe-core), writes `a11y-report.json`, and exits non-zero on any violation at or above an impact threshold (default `serious`). It catches what a static scan can't — computed ARIA, focus order, real rendered contrast.
 
 The runtime audit drives Playwright, which needs a browser binary once per machine:
 
@@ -874,9 +924,9 @@ pnpm exec playwright install chromium
 ```
 
 ```bash
-tessera a11y                      # audit (threshold: serious)
-tessera a11y --threshold minor    # stricter
-tessera a11y --build              # force a fresh build first
+pnpm exec tessera a11y                   # audit (threshold: serious)
+pnpm exec tessera a11y --threshold minor # stricter
+pnpm exec tessera a11y --build           # force a fresh build first
 ```
 
 The audit renders the course with the web adapter, so it works regardless of your `export.standard` — you don't need an LMS to run it.

package/README.md

@@ -2,22 +2,22 @@
 
 LMS tracking runtime for interactive learning content. One adapter layer (SCORM 1.2, SCORM 2004 4th Edition, cmi5, static Web), your choice of components.
 
-Tessera is a toolkit for building interactive online courses, designed for AI-assisted authoring: pages are `.svelte` files, the runtime locks the LMS data contract (tracking, completion, scoring, persistence), and an AI agent working in the project follows the conventions in `AGENTS.md` to write pages and components. This package is the runtime; you typically don't depend on it directly — `create-tessera` scaffolds a project that pins it for you.
+Tessera is a toolkit for building interactive online courses, designed for AI-assisted authoring: pages are `.svelte` files, the runtime locks the LMS data contract (tracking, completion, scoring, persistence), and an AI agent working in the workspace follows the conventions in `AGENTS.md` to write pages and components. This package is the runtime; you typically don't depend on it directly — `create-tessera` scaffolds a workspace that pins it for you. A workspace is one package that holds many courses under `courses/<name>/` and a `shared/` design system imported as `$shared`.
 
 ## Install
 
 You probably don't want to install this package directly. Use the scaffolder:
 
 ```bash
-npm create tessera@latest my-course
+pnpm create tessera@latest my-course
 ```
 
-That creates a project with Tessera wired up, a starter page structure, and the authoring guide (`AGENTS.md`) at the project root. Prefer hooks-only? `npm create tessera@latest -- --template=bare my-course` scaffolds without the built-in components.
+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>`.
 
 ## What's included
 
 - **Hooks** (`tessera-learn`): `useQuestion`, `useQuiz`, `useNavigation`, `useProgress`, `usePersistence`, `useXAPI`.
-- **Vite plugin** (`tessera-learn/plugin`): `tesseraPlugin()` — wires page/layout discovery, the LMS adapter, and the export pipeline. The `tessera` CLI (`dev`/`export`) runs Vite with this plugin for you, so scaffolded projects need no `vite.config.js`.
+- **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`.
 - **Accessibility checks**: static rules (alt text, media titles/captions, heading order, contrast, `<html lang>`) run inside validation and the build with zero extra dependencies; an opt-in runtime audit (`tessera a11y`, with `playwright` + `@axe-core/playwright` as optional peers) renders every page and gates on axe-core violations.

package/dist/{audit-CzKAXy3Y.js → audit-BNrvFHq_.js}

@@ -1,4 +1,4 @@
-import { basename, extname, relative, resolve } from "node:path";
+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";
@@ -1347,6 +1347,19 @@ function crossValidate(config, pageResults, errors, warnings) {
 	}
 }
 //#endregion
+//#region src/plugin/package-root.ts
+function resolvePackageRoot() {
+	const dir = import.meta.dirname;
+	for (let up = dir; up !== dirname(up); up = dirname(up)) {
+		const pkgPath = resolve(up, "package.json");
+		if (existsSync(pkgPath)) try {
+			const { name } = JSON.parse(readFileSync(pkgPath, "utf-8"));
+			if (name === "tessera-learn") return up;
+		} catch {}
+	}
+	return resolve(dir, "..", "..");
+}
+//#endregion
 //#region src/plugin/a11y/audit.ts
 const IMPACT_RANK = {
 	minor: 1,
@@ -1419,7 +1432,7 @@ async function loadDeps() {
 * reuses) dist/, serves it, drives Playwright + axe-core over each page, writes
 * a11y-report.json, and returns a process exit code (0 pass, 1 fail/error).
 */
-async function runAudit(projectRoot, options = {}) {
+async function runAudit(projectRoot, workspaceRoot, options = {}) {
 	const threshold = options.threshold ?? "serious";
 	const deps = await loadDeps();
 	if (!deps.ok) {
@@ -1433,8 +1446,8 @@ async function runAudit(projectRoot, options = {}) {
 	const disableRules = axeIgnoreRules(settings.ignore);
 	const manifest = generateManifest(resolve(projectRoot, "pages"));
 	const vite = await import("vite");
-	const { resolveTesseraConfig } = await import("./inline-config-DYHT51G8.js");
-	const auditBaseConfig = await resolveTesseraConfig(projectRoot, {
+	const { resolveTesseraConfig } = await import("./inline-config-Dudu5r8w.js");
+	const auditBaseConfig = await resolveTesseraConfig(projectRoot, workspaceRoot, {
 		command: "build",
 		mode: "production"
 	});
@@ -1497,23 +1510,29 @@ async function runAudit(projectRoot, options = {}) {
 					nodes: v.nodes.length
 				}));
 			};
-			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();
@@ -1521,17 +1540,24 @@ async function runAudit(projectRoot, 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");
@@ -1549,6 +1575,10 @@ async function runAudit(projectRoot, 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;
@@ -1558,10 +1588,20 @@ function printSummary(report, reportPath) {
 		for (const v of p.violations) console.log(`      [${v.impact ?? "n/a"}] ${v.id} — ${v.help} (${v.nodes} node${v.nodes === 1 ? "" : "s"})`);
 	}
 	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 { normalizeA11y as a, generateManifest as c, isPlausibleLanguageTag as i, readCourseConfig as l, runAudit as n, reportValidationIssues as o, isIgnored as r, validateProject as s, AUDIT_ENV_FLAG as t };
+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-CzKAXy3Y.js.map
+//# sourceMappingURL=audit-BNrvFHq_.js.map