tessera-learn 0.0.13 → 0.2.0

package/src/runtime/xapi/derive-actor.ts

@@ -3,54 +3,48 @@ import type { SCORM12API } from '../adapters/scorm12.js';
 import type { SCORM2004API } from '../adapters/scorm2004.js';
 
 /**
- * Compute the default SCORM-derived `account.homePage` from the activity
- * IRI. Returns the URL origin when `activityId` is an http(s) URL,
- * otherwise null. Callers that get null and have no `actorAccountHomePage`
- * override should treat it as a config error (the build-time validator
- * already enforces this; this is a runtime fallback for completeness).
+ * Origin of an http(s) URL, else null. Shared with the config validator, which
+ * predicts this result to know when `actorAccountHomePage` becomes required —
+ * one helper keeps the two in lockstep.
  */
-export function defaultAccountHomePage(activityId: string): string | null {
+export function httpOrigin(url: string): string | null {
   try {
-    const url = new URL(activityId);
-    if (url.protocol === 'http:' || url.protocol === 'https:') {
-      return url.origin;
-    }
-    return null;
+    const parsed = new URL(url);
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:'
+      ? parsed.origin
+      : null;
   } catch {
     return null;
   }
 }
 
 /**
- * Synthesize an Identified Agent for SCORM 1.2 from the LMS data model.
+ * Synthesize an Identified Agent from the SCORM learner fields.
  *
- *   { account: { homePage, name: cmi.core.student_id },
- *     name: cmi.core.student_name,
- *     objectType: 'Agent' }
+ *   { account: { homePage, name: <id> }, name: <name>, objectType: 'Agent' }
  *
  * The `account` IFI satisfies xAPI's Identified Agent rule. `homePage`
- * defaults to the activityId origin so analytics keyed on actor identity
- * stay stable across LMS hosts; the author's `actorAccountHomePage`
- * overrides when the authority namespace is elsewhere.
- *
- * Returns null if `student_id` is missing — caller should not construct
- * a publisher in that case (the LRS would 400 on every send anyway).
+ * defaults to the activityId origin so analytics keyed on actor identity stay
+ * stable across LMS hosts; the author's `actorAccountHomePage` overrides when
+ * the authority namespace is elsewhere. Returns null if the id is missing —
+ * the caller should not construct a publisher (the LRS would 400 every send).
  */
-export function synthesizeSCORM12Actor(
-  api: SCORM12API,
+function synthesizeActor(
+  readId: () => string,
+  readName: () => string,
   activityId: string,
   actorAccountHomePage?: string,
 ): XAPIAgent | null {
   let id = '';
   let name = '';
   try {
-    id = api.LMSGetValue('cmi.core.student_id') || '';
+    id = readId() || '';
   } catch {}
   try {
-    name = api.LMSGetValue('cmi.core.student_name') || '';
+    name = readName() || '';
   } catch {}
   if (!id) return null;
-  const homePage = actorAccountHomePage ?? defaultAccountHomePage(activityId);
+  const homePage = actorAccountHomePage ?? httpOrigin(activityId);
   if (!homePage) return null;
   const agent: XAPIAgent = {
     account: { homePage, name: id },
@@ -60,31 +54,30 @@ export function synthesizeSCORM12Actor(
   return agent;
 }
 
-/**
- * Synthesize an Identified Agent for SCORM 2004 from the LMS data model.
- * Same structure as SCORM 1.2 but reads from `cmi.learner_id` /
- * `cmi.learner_name` (the renamed 2004 fields).
- */
+/** SCORM 1.2 actor from `cmi.core.student_id` / `cmi.core.student_name`. */
+export function synthesizeSCORM12Actor(
+  api: SCORM12API,
+  activityId: string,
+  actorAccountHomePage?: string,
+): XAPIAgent | null {
+  return synthesizeActor(
+    () => api.LMSGetValue('cmi.core.student_id'),
+    () => api.LMSGetValue('cmi.core.student_name'),
+    activityId,
+    actorAccountHomePage,
+  );
+}
+
+/** SCORM 2004 actor from `cmi.learner_id` / `cmi.learner_name` (renamed 2004 fields). */
 export function synthesizeSCORM2004Actor(
   api: SCORM2004API,
   activityId: string,
   actorAccountHomePage?: string,
 ): XAPIAgent | null {
-  let id = '';
-  let name = '';
-  try {
-    id = api.GetValue('cmi.learner_id') || '';
-  } catch {}
-  try {
-    name = api.GetValue('cmi.learner_name') || '';
-  } catch {}
-  if (!id) return null;
-  const homePage = actorAccountHomePage ?? defaultAccountHomePage(activityId);
-  if (!homePage) return null;
-  const agent: XAPIAgent = {
-    account: { homePage, name: id },
-    objectType: 'Agent',
-  };
-  if (name) agent.name = name;
-  return agent;
+  return synthesizeActor(
+    () => api.GetValue('cmi.learner_id'),
+    () => api.GetValue('cmi.learner_name'),
+    activityId,
+    actorAccountHomePage,
+  );
 }

package/src/runtime/xapi/publisher.ts

@@ -482,18 +482,22 @@ export class XAPIPublisher {
       }));
   }
 
+  #buildHeaders(token: string): Headers {
+    const headers = new Headers();
+    if (token) headers.set('Authorization', `Basic ${token}`);
+    headers.set('X-Experience-API-Version', X_API_VERSION);
+    headers.set('Content-Type', 'application/json');
+    return headers;
+  }
+
   #fetchWithToken(
     token: string,
     body: string,
     keepalive: boolean,
   ): Promise<SendOutcome> {
-    const headers = new Headers();
-    if (token) headers.set('Authorization', `Basic ${token}`);
-    headers.set('X-Experience-API-Version', X_API_VERSION);
-    headers.set('Content-Type', 'application/json');
     return fetch(this.#statementsUrl, {
       method: 'POST',
-      headers,
+      headers: this.#buildHeaders(token),
       body,
       keepalive,
     })
@@ -521,18 +525,14 @@ export class XAPIPublisher {
     ) {
       this.#cachedAuth = null;
       return this.#resolveAuth(true)
-        .then((newToken) => {
-          const retryHeaders = new Headers();
-          if (newToken) retryHeaders.set('Authorization', `Basic ${newToken}`);
-          retryHeaders.set('X-Experience-API-Version', X_API_VERSION);
-          retryHeaders.set('Content-Type', 'application/json');
-          return fetch(this.#statementsUrl, {
+        .then((newToken) =>
+          fetch(this.#statementsUrl, {
             method: 'POST',
-            headers: retryHeaders,
+            headers: this.#buildHeaders(newToken),
             body,
             keepalive,
-          });
-        })
+          }),
+        )
         .then((retryResp): SendOutcome => {
           if (retryResp.ok || retryResp.status === 409) {
             return { ok: true, status: retryResp.status };

package/src/runtime/xapi/setup.ts

@@ -90,6 +90,10 @@ function makeSCORMDevFallbackPublisher(
  * adapter present in non-cmi5 export modes — the validator should have
  * caught this at build time).
  */
+type ActorResolution =
+  | { kind: 'actor'; value: XAPIAgent | (() => XAPIAgent | Promise<XAPIAgent>) }
+  | { kind: 'scorm-fallback'; standard: 'scorm12' | 'scorm2004' };
+
 function resolveDestination(
   entry: XAPIConfig,
   config: CourseConfig,
@@ -114,24 +118,18 @@ function resolveDestination(
 
   // Explicit endpoint.
   const explicit = entry as XAPIExplicitConfig;
-  const actorOrResolver = resolveExplicitActor(explicit, config, adapter);
-  if (actorOrResolver === null) return null;
-  if (
-    typeof actorOrResolver === 'object' &&
-    (actorOrResolver as { __scormDevFallback?: 'scorm12' | 'scorm2004' })
-      .__scormDevFallback
-  ) {
-    const std = (
-      actorOrResolver as { __scormDevFallback: 'scorm12' | 'scorm2004' }
-    ).__scormDevFallback;
-    return { kind: 'explicit', publisher: makeSCORMDevFallbackPublisher(std) };
+  const resolution = resolveExplicitActor(explicit, config, adapter);
+  if (resolution === null) return null;
+  if (resolution.kind === 'scorm-fallback') {
+    return {
+      kind: 'explicit',
+      publisher: makeSCORMDevFallbackPublisher(resolution.standard),
+    };
   }
   const publisher = new XAPIPublisher({
     endpoint: explicit.endpoint,
     auth: explicit.auth,
-    actor: actorOrResolver as
-      | XAPIAgent
-      | (() => XAPIAgent | Promise<XAPIAgent>),
+    actor: resolution.value,
     activityId: explicit.activityId,
     registration: explicit.registration,
   });
@@ -149,50 +147,45 @@ function resolveExplicitActor(
   explicit: XAPIExplicitConfig,
   config: CourseConfig,
   adapter: PersistenceAdapter | null,
-):
-  | XAPIAgent
-  | (() => XAPIAgent | Promise<XAPIAgent>)
-  | { __scormDevFallback: 'scorm12' | 'scorm2004' }
-  | null {
-  if (explicit.actor !== undefined) return explicit.actor;
-  // No author-supplied actor — try mode-specific derivation.
+): ActorResolution | null {
+  if (explicit.actor !== undefined) {
+    return { kind: 'actor', value: explicit.actor };
+  }
   if (config.export?.standard === 'cmi5' && adapter instanceof CMI5Adapter) {
     const inner = adapter.getPublisher();
-    if (inner) {
-      // The cmi5 adapter's publisher has the launch actor cached.
-      try {
-        return inner.getActor();
-      } catch {
-        return null;
-      }
+    if (!inner) return null;
+    try {
+      return { kind: 'actor', value: inner.getActor() };
+    } catch {
+      return null;
     }
-    return null;
   }
   if (config.export?.standard === 'scorm12') {
     if (adapter instanceof SCORM12Adapter) {
-      return synthesizeSCORM12Actor(
-        adapter.getAPI(),
-        explicit.activityId,
-        explicit.actorAccountHomePage,
-      );
+      return {
+        kind: 'actor',
+        value: synthesizeSCORM12Actor(
+          adapter.getAPI(),
+          explicit.activityId,
+          explicit.actorAccountHomePage,
+        ) as XAPIAgent,
+      };
     }
-    // Adapter is the WebAdapter dev fallback. Mirror the cmi5 'lms'
-    // dev-fallback path: install a stub publisher that surfaces an
-    // explicit error rather than silently no-oping. Authors get the
-    // same dev/prod parity in SCORM that they get in cmi5.
-    return { __scormDevFallback: 'scorm12' };
+    return { kind: 'scorm-fallback', standard: 'scorm12' };
   }
   if (config.export?.standard === 'scorm2004') {
     if (adapter instanceof SCORM2004Adapter) {
-      return synthesizeSCORM2004Actor(
-        adapter.getAPI(),
-        explicit.activityId,
-        explicit.actorAccountHomePage,
-      );
+      return {
+        kind: 'actor',
+        value: synthesizeSCORM2004Actor(
+          adapter.getAPI(),
+          explicit.activityId,
+          explicit.actorAccountHomePage,
+        ) as XAPIAgent,
+      };
     }
-    return { __scormDevFallback: 'scorm2004' };
+    return { kind: 'scorm-fallback', standard: 'scorm2004' };
   }
-  // Web export with no actor — build-time validator should have errored.
   console.warn(
     'Tessera xAPI: explicit destination has no actor and no derivation source — skipping.',
   );

package/templates/course/course.config.js

@@ -0,0 +1,11 @@
+export default {
+  title: '__PROJECT_TITLE__',
+  language: 'en',
+  navigation: { mode: 'free' },
+  completion: { mode: 'percentage', percentageThreshold: 100 },
+  scoring: { passingScore: 70 },
+  branding: {
+    primaryColor: '#0066cc',
+  },
+  export: { standard: 'web' },
+};

package/templates/course/layout.svelte

@@ -0,0 +1,116 @@
+<script>
+  import '$shared/tokens.css';
+  import { useNavigation, useProgress } from 'tessera-learn';
+
+  let { page } = $props();
+  const nav = useNavigation();
+  const progress = useProgress();
+</script>
+
+<div class="course">
+  <header>
+    <h1>__PROJECT_TITLE__</h1>
+    <span class="progress"
+      >{progress.visitedPages.size} / {nav.pages.length}</span
+    >
+  </header>
+
+  <main>
+    {@render page()}
+  </main>
+
+  <footer>
+    <button
+      class="nav-btn"
+      disabled={!nav.canGoPrev}
+      onclick={() => nav.prev()}
+    >
+      ← Previous
+    </button>
+    <button
+      class="nav-btn nav-btn--primary"
+      disabled={!nav.canGoNext}
+      onclick={() => nav.next()}
+    >
+      Next →
+    </button>
+  </footer>
+</div>
+
+<style>
+  .course {
+    display: flex;
+    flex-direction: column;
+    min-height: 100vh;
+  }
+
+  header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--tessera-spacing-md);
+    padding: var(--tessera-spacing-md) var(--tessera-spacing-xl);
+    border-bottom: 1px solid var(--tessera-border);
+  }
+
+  header h1 {
+    margin: 0;
+    font-size: 1.125rem;
+  }
+
+  .progress {
+    flex: none;
+    padding: 0.15rem 0.6rem;
+    border-radius: 999px;
+    background: var(--tessera-bg-secondary);
+    color: var(--tessera-text-light);
+    font-size: 0.875rem;
+  }
+
+  main {
+    flex: 1;
+    width: 100%;
+    max-width: var(--tessera-content-max-width);
+    margin: 0 auto;
+    padding: var(--tessera-spacing-xl);
+  }
+
+  footer {
+    display: flex;
+    justify-content: space-between;
+    gap: var(--tessera-spacing-md);
+    padding: var(--tessera-spacing-md) var(--tessera-spacing-xl);
+    border-top: 1px solid var(--tessera-border);
+  }
+
+  .nav-btn {
+    padding: 0.5rem 1rem;
+    border: 1px solid var(--tessera-border);
+    border-radius: 6px;
+    background: var(--tessera-bg);
+    color: var(--tessera-text);
+    cursor: pointer;
+    transition:
+      background var(--tessera-transition-fast),
+      border-color var(--tessera-transition-fast);
+  }
+
+  .nav-btn:hover:not(:disabled) {
+    background: var(--tessera-bg-secondary);
+  }
+
+  .nav-btn--primary {
+    border-color: transparent;
+    background: var(--tessera-primary);
+    color: #fff;
+  }
+
+  .nav-btn--primary:hover:not(:disabled) {
+    background: var(--tessera-primary-dark);
+  }
+
+  .nav-btn:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+</style>

package/templates/course/pages/01-getting-started/01-welcome/_meta.js

@@ -0,0 +1 @@
+export default { title: 'Welcome', pages: ['welcome'] };

package/templates/course/pages/01-getting-started/01-welcome/welcome.svelte

@@ -0,0 +1,19 @@
+<script module>
+  export const pageConfig = { title: 'Welcome' };
+</script>
+
+<script>
+  import Button from '$shared/Button.svelte';
+</script>
+
+<h1>Welcome to __PROJECT_TITLE__</h1>
+
+<p>This is a basic demo page of your Tessera course.</p>
+
+<p>
+  Point your agent to <code>AGENTS.md</code> at the workspace root for the
+  authoring guide. The button below is imported from the workspace design system
+  via <code>$shared</code>.
+</p>
+
+<Button>A shared button</Button>

package/templates/course/pages/01-getting-started/_meta.js

@@ -0,0 +1 @@
+export default { title: 'Getting Started' };

package/templates/course/styles/custom.css

@@ -0,0 +1,5 @@
+/* Course-level CSS overrides.
+ * Imported automatically by Tessera. Use this file for tweaks on top of the
+ * default theme. For deeper customisation, see the "Theming" section in
+ * AGENTS.md.
+ */

package/dist/audit-BBJpQGqb.js

@@ -1,204 +0,0 @@
-import { o as generateManifest, r as normalizeA11y, s as readCourseConfig } from "./validation-B-xTvM9B.js";
-import { resolve } from "node:path";
-import { existsSync, writeFileSync } from "node:fs";
-//#region src/plugin/a11y/audit.ts
-const IMPACT_RANK = {
-	minor: 1,
-	moderate: 2,
-	serious: 3,
-	critical: 4
-};
-const AUDIT_ENV_FLAG = "TESSERA_A11Y_AUDIT";
-/** Map the `a11y.standard` enum to axe's cumulative `runOnly` tag list. */
-function axeTags(standard) {
-	switch (standard) {
-		case "wcag2a": return ["wcag2a"];
-		case "wcag21aa": return [
-			"wcag2a",
-			"wcag2aa",
-			"wcag21a",
-			"wcag21aa"
-		];
-		default: return ["wcag2a", "wcag2aa"];
-	}
-}
-/** axe-applicable ignore entries: drop the Tier-1a/1b namespaces. */
-function axeIgnoreRules(ignore) {
-	return ignore.filter((id) => !id.startsWith("tessera/") && !id.startsWith("a11y_"));
-}
-function isFailing(v, thresholdRank) {
-	return !v.impact || IMPACT_RANK[v.impact] >= thresholdRank;
-}
-async function tryImport(specifier) {
-	return import(specifier);
-}
-async function loadDeps() {
-	let chromium;
-	for (const spec of ["playwright", "@playwright/test"]) try {
-		const mod = await tryImport(spec);
-		if (mod.chromium) {
-			chromium = mod.chromium;
-			break;
-		}
-	} catch {}
-	if (!chromium) return {
-		ok: false,
-		missing: "playwright"
-	};
-	try {
-		const mod = await tryImport("@axe-core/playwright");
-		if (!mod.default) return {
-			ok: false,
-			missing: "@axe-core/playwright"
-		};
-		return {
-			ok: true,
-			deps: {
-				chromium,
-				AxeBuilder: mod.default
-			}
-		};
-	} catch {
-		return {
-			ok: false,
-			missing: "@axe-core/playwright"
-		};
-	}
-}
-/**
-* Run the Tier-2 runtime accessibility audit against a built course. Builds (or
-* 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 = {}) {
-	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    npm i -D playwright @axe-core/playwright\n    npx playwright install chromium");
-		return 1;
-	}
-	const { chromium, AxeBuilder } = deps.deps;
-	const read = readCourseConfig(projectRoot);
-	const settings = normalizeA11y(read.ok ? read.config.a11y : void 0);
-	const tags = axeTags(settings.standard);
-	const disableRules = axeIgnoreRules(settings.ignore);
-	const manifest = generateManifest(resolve(projectRoot, "pages"));
-	const vite = await import("vite");
-	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({
-				root: projectRoot,
-				build: {
-					outDir: auditDist,
-					emptyOutDir: true
-				},
-				logLevel: "warn"
-			});
-		}
-		server = await vite.preview({
-			root: projectRoot,
-			build: { outDir: auditDist },
-			preview: {
-				port: 0,
-				host: "127.0.0.1"
-			},
-			logLevel: "warn"
-		});
-		const baseUrl = server.resolvedUrls?.local?.[0];
-		if (!baseUrl) {
-			console.error("[tessera a11y] Could not determine preview server URL.");
-			return 1;
-		}
-		const browser = await chromium.launch();
-		const pages = [];
-		try {
-			const page = await (await browser.newContext()).newPage();
-			const auditUrl = new URL(baseUrl);
-			auditUrl.searchParams.set("__tessera_audit", "1");
-			await page.goto(auditUrl.href, { waitUntil: "networkidle" });
-			await page.waitForSelector("#tessera-app", { timeout: 2e4 });
-			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
-				}));
-			};
-			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,
-					title,
-					violations: await scan()
-				});
-			}
-		} finally {
-			await browser.close();
-		}
-		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++;
-		}
-		const report = {
-			standard: settings.standard,
-			threshold,
-			pages,
-			totalViolations,
-			failingViolations,
-			passed: failingViolations === 0
-		};
-		const reportPath = resolve(projectRoot, "a11y-report.json");
-		writeFileSync(reportPath, JSON.stringify(report, null, 2), "utf-8");
-		printSummary(report, reportPath);
-		return report.passed ? 0 : 1;
-	} catch (err) {
-		console.error(`\x1b[31m[tessera a11y]\x1b[0m Audit could not complete: ${err instanceof Error ? err.message : String(err)}`);
-		return 1;
-	} finally {
-		server?.httpServer?.close?.();
-		if (prevEnv === void 0) delete process.env[AUDIT_ENV_FLAG];
-		else process.env[AUDIT_ENV_FLAG] = prevEnv;
-	}
-}
-function printSummary(report, reportPath) {
-	const thresholdRank = IMPACT_RANK[report.threshold];
-	for (const p of report.pages) {
-		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"})`);
-	}
-	console.log(`\n[tessera a11y] Report written to ${reportPath}`);
-	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).`);
-}
-//#endregion
-export { runAudit as n, AUDIT_ENV_FLAG as t };
-
-//# sourceMappingURL=audit-BBJpQGqb.js.map