tessera-learn 0.0.3 → 0.0.4

package/AGENTS.md

@@ -88,7 +88,7 @@ Pages listed in `pages` come first in listed order; any unlisted `.svelte` files
 There are five:
 
 1. **Built-in components**: `Callout`, `Image`, `MultipleChoice`, `FillInTheBlank`, `Matching`, `Sorting`, etc., from `tessera-learn`. Use, compose, or skip.
-2. **Hooks**: `useQuestion`, `useQuiz`, `useNavigation`, `useProgress`, `usePersistence`. The stable contract between custom widgets and the runtime. Anything the built-ins do, you can do.
+2. **Hooks**: `useQuestion`, `useQuiz`, `useNavigation`, `useProgress`, `useCompletion`, `usePersistence`. The stable contract between custom widgets and the runtime. Anything the built-ins do, you can do.
 3. **Custom layout**: drop `layout.svelte` at the project root to replace the default chrome.
 4. **Custom quiz shell**: drop `quiz.svelte` at the project root to replace the built-in quiz UI for every page that has `pageConfig.quiz`. Authors call `useQuiz()` for state and dispatch; question widgets continue to register through `useQuestion`.
 5. **Custom xAPI**: `useXAPI()` returns a publisher for emitting your own xAPI verbs to one or more LRSes. See [Custom xAPI statements](#custom-xapi-statements).
@@ -404,6 +404,95 @@ Standalone questions are not graded by default. To grade one (e.g., a required r
 
 ---
 
+## Manual completion
+
+`completion.mode: "manual"` is for courses where the author — not a quiz score or a page-visit ratio — owns the moment of completion. Two examples:
+
+- A short policy briefing where reading the final page **is** the proof of completion.
+- A compliance "click to acknowledge" button at the end of a module.
+
+Under manual mode, **both** triggers below are always active. First-to-fire wins; subsequent calls are idempotent.
+
+### Trigger A: page frontmatter
+
+Declare `completesOn: "view"` on any page. Completion fires the moment that page renders.
+
+```svelte
+<!-- pages/05-summary/finale.svelte -->
+<script module>
+  export const pageConfig = {
+    title: "You're done",
+    completesOn: "view",
+  };
+</script>
+
+<h1>Thanks for completing the briefing.</h1>
+```
+
+`completesOn` accepts the literal string `"view"` (only value in v1). The page is marked visited and completion fires in the same effect — the LMS sees one `setCompletionStatus("complete")` immediately after the page renders.
+
+### Trigger B: runtime hook
+
+```svelte
+<script>
+  import { useCompletion } from 'tessera-learn';
+
+  const { markComplete, completionStatus } = useCompletion();
+</script>
+
+<button
+  onclick={() => markComplete()}
+  disabled={completionStatus === 'complete'}
+>
+  I acknowledge
+</button>
+
+{#if completionStatus === 'complete'}
+  <p>Recorded. You may now close this window.</p>
+{/if}
+```
+
+Composes cleanly with custom widgets, modal close handlers, video-ended events, timer expirations, etc. Calling `markComplete()` outside `completion.mode: "manual"` is a no-op with a one-shot dev warning per session — safe to leave in shared components.
+
+### `completion.trigger` (build-time check)
+
+Optional. Set to `"page"` to fail the build when no page declares `completesOn: "view"`. Useful when the page-view path is load-bearing and a typo should fail the build, not the launch. Both triggers still work either way; the field only adds a static check.
+
+```js
+completion: { mode: "manual", trigger: "page" }
+```
+
+When omitted, the dev runtime warns once after 60 s if completion has not fired — a safety net that covers both "no `completesOn` page exists" and "the hook is never called" cases.
+
+### Success status
+
+By default `successStatus` stays `"unknown"` under manual — the LMS sees completion without a pass/fail verdict. If you want completion **and** an automatic pass (typical for "acknowledge" flows):
+
+```js
+completion: { mode: "manual", requireSuccessStatus: "passed" }  // or "failed"
+```
+
+| Adapter        | What the LMS sees on `markComplete()` (no `requireSuccessStatus`)  |
+| -------------- | ------------------------------------------------------------------ |
+| SCORM 1.2      | `cmi.core.lesson_status = "completed"`                             |
+| SCORM 2004 4th | `cmi.completion_status = "completed"`, `cmi.success_status = "unknown"` |
+| cmi5           | **Completed** statement (no Passed / Failed)                       |
+| web            | `localStorage` only                                                |
+
+With `requireSuccessStatus: "passed"`, SCORM 1.2 writes `lesson_status = "passed"`, SCORM 2004 writes `success_status = "passed"`, and cmi5 emits a **Passed** statement alongside **Completed**.
+
+### Quizzes under manual mode
+
+A graded quiz under `mode: "manual"` reports its score to the LMS gradebook but does **not** drive completion or success — `markComplete()` / `completesOn` does. The build emits a warning to make this explicit. Set `graded: false` (or remove the quiz) if that's not what you want.
+
+### Non-goals
+
+- Combining manual + quiz/percentage rules ("complete when X **and** quiz passed"). Use a `useCompletion()` call inside a custom `$effect` if you need conditional logic.
+- Per-learner conditional completion expressed in config — same answer: do it in a component with `useCompletion()`.
+- Marking a course **incomplete** after it has been completed. Completion is monotonic in every spec we target. The runtime ignores re-marks.
+
+---
+
 ## Assets
 
 Drop files into `assets/`. Reference them with `$assets/` in component props:
@@ -486,12 +575,14 @@ export default {
   },
 
   completion: {
-    mode: "percentage",             // "percentage" or "quiz"
+    mode: "percentage",             // "percentage" | "quiz" | "manual"
     percentageThreshold: 100,       // 0–100 (percentage mode)
+    // trigger: "page",              // (manual only) opt into build-time check
+    // requireSuccessStatus: "passed", // (manual only) "passed" | "failed"
   },
 
   scoring: {
-    passingScore: 70,
+    passingScore: 70,               // optional under "manual" (defaults to 0)
   },
 
   export: {
@@ -504,6 +595,7 @@ export default {
 - `navigation.mode: "sequential"` → pages unlock one at a time as each is completed.
 - `completion.mode: "percentage"` → course completes when `visitedPages / totalPages * 100 >= percentageThreshold`.
 - `completion.mode: "quiz"` → course completes when graded quiz average >= `scoring.passingScore`.
+- `completion.mode: "manual"` → course completes when an author-declared trigger fires: a page declares `pageConfig.completesOn: "view"`, or any component calls `useCompletion().markComplete()`. First-to-fire wins. `scoring.passingScore` is optional (defaults to 0). See [Manual completion](#manual-completion).
 
 ### Minimum config
 
@@ -568,7 +660,7 @@ The Vite plugin runs project validation on every dev start and build (manifest s
 
 ## Hooks Reference
 
-Five hooks plus one helper make up the stable contract between widgets and the runtime.
+Six hooks plus one helper make up the stable contract between widgets and the runtime.
 
 ```js
 import {
@@ -576,6 +668,7 @@ import {
   useQuiz,
   useNavigation,
   useProgress,
+  useCompletion,
   usePersistence,
   isCorrect,
 } from 'tessera-learn';
@@ -704,6 +797,18 @@ function useProgress(): {
 };
 ```
 
+### `useCompletion`
+
+Trigger course completion from any component, and reactively read the current completion status. Active under `completion.mode: "manual"`; in any other mode `markComplete()` is a no-op with a one-shot dev warning. See [Manual completion](#manual-completion).
+
+```ts
+function useCompletion(): {
+  /** Idempotent — only the first call per session has an effect. */
+  markComplete(): void;
+  readonly completionStatus: 'incomplete' | 'complete';
+};
+```
+
 ### `usePersistence<T>(key)`
 
 Per-widget persistent state. Survives reload on every adapter: `localStorage` for web, SCORM `cmi.suspend_data` for SCORM 1.2/2004, xAPI State API for cmi5. Reads sync; writes batched by the adapter. JSON-serializable values only.
@@ -882,6 +987,7 @@ The runtime translates author intent (page visits, quiz scores, completion, pers
 | State persisted (page visited, bookmark moved, chunk revealed, `usePersistence` write, etc.) | `LMSSetValue("cmi.suspend_data", json)` (microtask-coalesced) | `SetValue("cmi.suspend_data", json)` (microtask-coalesced) | State API `PUT` `tessera-state` document, chained on the publisher queue |
 | Graded quiz scored | `LMSSetValue("cmi.core.score.raw"\|"min"\|"max", …)` then `LMSSetValue("cmi.core.lesson_status", "passed"\|"failed")` | `SetValue("cmi.score.raw"\|"min"\|"max"\|"scaled", …)` then `SetValue("cmi.success_status", "passed"\|"failed")` | **Passed** or **Failed** statement, with `result.score.scaled` and `result.duration` (one-shot per session) |
 | Course completion changes | Funneled into `cmi.core.lesson_status` (only one field exists) | `SetValue("cmi.completion_status", "completed"\|"incomplete")` | **Completed** statement with `result.completion = true`, `result.duration`, `result.score?` (one-shot per session) |
+| Author marks complete (`completion.mode: "manual"`) | `cmi.core.lesson_status = "completed"` (or `"passed"`/`"failed"` if `requireSuccessStatus` set) | `cmi.completion_status = "completed"`; `cmi.success_status = "unknown"` (or `"passed"`/`"failed"` if `requireSuccessStatus` set) | **Completed** statement; **Passed**/**Failed** if `requireSuccessStatus` set |
 | Question answered (graded or standalone, inside or outside a quiz) | `cmi.interactions.{n}.id` / `student_response` / `result` / `time` / `type` (n continues from prior `_count`) | `cmi.interactions.{n}.id` / `learner_response` / `result` / `timestamp` / `type` (n continues from prior `_count`) | **Answered** statement; object `${activityId}#${questionId}`, definition `cmi.interaction` + `interactionType`, `result.response`, `result.success` |
 | Resume after reload | Read `cmi.suspend_data` on init; manifest is rebuilt from code, not LMS | Read `cmi.suspend_data` on init | State API `GET` `tessera-state`; lifecycle replays from where the prior session left off |
 | Author exit / unload | `LMSSetValue("cmi.core.exit", "suspend"\|"")`, `LMSCommit("")`, `LMSFinish("")` (queue drained synchronously) | `SetValue("cmi.exit", "suspend"\|"normal"\|...)`, `Commit("")`, `Terminate("")` (queue drained synchronously) | If course not yet **Completed**, send **Suspended**; then **Terminated** (always last on the wire, cmi5 §9.3.6) |

package/dist/plugin/index.js

@@ -207,7 +207,8 @@ function generateManifest(pagesDir) {
 					title: pageConfig.title || titleCase(pageSlug),
 					slug: pageSlug,
 					importPath: relativePath,
-					quiz: pageConfig.quiz || null
+					quiz: pageConfig.quiz || null,
+					...pageConfig.completesOn === "view" ? { completesOn: "view" } : {}
 				};
 				lesson.pages.push(page);
 				flatPages.push(page);
@@ -305,13 +306,19 @@ const KNOWN_CONFIG_FIELDS = new Set([
 	"xapi"
 ]);
 const VALID_NAV_MODES = ["free", "sequential"];
-const VALID_COMPLETION_MODES = ["quiz", "percentage"];
+const VALID_COMPLETION_MODES = [
+	"quiz",
+	"percentage",
+	"manual"
+];
 const VALID_EXPORT_STANDARDS = [
 	"web",
 	"scorm12",
 	"scorm2004",
 	"cmi5"
 ];
+const VALID_MANUAL_TRIGGERS = ["page"];
+const VALID_REQUIRE_SUCCESS_STATUS = ["passed", "failed"];
 /**
 * Validate a Tessera project at the given root.
 * Returns errors (block build) and warnings (informational).
@@ -355,7 +362,15 @@ function parseConfig(configPath, errors, warnings) {
 		if (!VALID_NAV_MODES.includes(config.navigation.mode)) errors.push(`course.config.js: "navigation.mode" must be "free" or "sequential", got "${config.navigation.mode}"`);
 	}
 	if (config.completion?.mode !== void 0) {
-		if (!VALID_COMPLETION_MODES.includes(config.completion.mode)) errors.push(`course.config.js: "completion.mode" must be "quiz" or "percentage", got "${config.completion.mode}"`);
+		if (!VALID_COMPLETION_MODES.includes(config.completion.mode)) errors.push(`course.config.js: "completion.mode" must be "quiz", "percentage", or "manual", got "${config.completion.mode}"`);
+	}
+	if (config.completion?.trigger !== void 0) {
+		if (config.completion.mode !== "manual") warnings.push(`course.config.js: "completion.trigger" is ignored unless completion.mode is "manual"`);
+		else if (!VALID_MANUAL_TRIGGERS.includes(config.completion.trigger)) errors.push(`course.config.js: "completion.trigger" must be "page" or omitted, got "${config.completion.trigger}"`);
+	}
+	if (config.completion?.requireSuccessStatus !== void 0) {
+		if (config.completion.mode !== "manual") warnings.push(`course.config.js: "completion.requireSuccessStatus" is ignored unless completion.mode is "manual"`);
+		else if (!VALID_REQUIRE_SUCCESS_STATUS.includes(config.completion.requireSuccessStatus)) errors.push(`course.config.js: "completion.requireSuccessStatus" must be "passed" or "failed" (omit for "unknown"), got "${config.completion.requireSuccessStatus}"`);
 	}
 	if (config.export?.standard !== void 0) {
 		if (!VALID_EXPORT_STANDARDS.includes(config.export.standard)) errors.push(`course.config.js: "export.standard" must be "web", "scorm12", "scorm2004", or "cmi5", got "${config.export.standard}"`);
@@ -490,6 +505,7 @@ function validateSingleXAPIEntry(entry, label, standard, errors, warnings) {
 function validatePages(pagesDir, assetsDir, projectRoot) {
 	const errors = [];
 	const warnings = [];
+	const pages = [];
 	let totalPages = 0;
 	let totalQuizzes = 0;
 	let hasGradedQuiz = false;
@@ -501,7 +517,8 @@ function validatePages(pagesDir, assetsDir, projectRoot) {
 			warnings,
 			totalPages: 0,
 			totalQuizzes: 0,
-			hasGradedQuiz: false
+			hasGradedQuiz: false,
+			pages
 		};
 	}
 	const topLevelEntries = readdirSync(pagesDir);
@@ -522,7 +539,8 @@ function validatePages(pagesDir, assetsDir, projectRoot) {
 			warnings,
 			totalPages: 0,
 			totalQuizzes: 0,
-			hasGradedQuiz: false
+			hasGradedQuiz: false,
+			pages
 		};
 	}
 	for (const sectionName of sectionDirs) {
@@ -546,12 +564,25 @@ function validatePages(pagesDir, assetsDir, projectRoot) {
 			const fileRel = relative(projectRoot, filePath);
 			const content = readSourceFileCached(filePath);
 			const pageConfig = validatePageConfig(content, fileRel, errors);
+			const navIndex = totalPages;
 			totalPages++;
+			let pageHasGradedQuiz = false;
 			if (pageConfig?.quiz) {
 				totalQuizzes++;
 				validateQuizConfig(pageConfig.quiz, fileRel, errors);
-				if (pageConfig.quiz.graded === true) hasGradedQuiz = true;
+				if (pageConfig.quiz.graded === true) {
+					hasGradedQuiz = true;
+					pageHasGradedQuiz = true;
+				}
 			}
+			const completesOnView = validateCompletesOn(pageConfig, fileRel, errors);
+			pages.push({
+				fileRel,
+				navIndex,
+				hasGradedQuiz: pageHasGradedQuiz,
+				hasQuiz: !!pageConfig?.quiz,
+				completesOnView
+			});
 			validateAssetRefs(content, fileRel, assetsDir, warnings, assetExistsCache);
 		}
 		const lessonDirs = sectionEntries.filter((name) => {
@@ -581,12 +612,25 @@ function validatePages(pagesDir, assetsDir, projectRoot) {
 				const fileRel = relative(projectRoot, filePath);
 				const content = readSourceFileCached(filePath);
 				const pageConfig = validatePageConfig(content, fileRel, errors);
+				const navIndex = totalPages;
 				totalPages++;
+				let pageHasGradedQuiz = false;
 				if (pageConfig?.quiz) {
 					totalQuizzes++;
 					validateQuizConfig(pageConfig.quiz, fileRel, errors);
-					if (pageConfig.quiz.graded === true) hasGradedQuiz = true;
+					if (pageConfig.quiz.graded === true) {
+						hasGradedQuiz = true;
+						pageHasGradedQuiz = true;
+					}
 				}
+				const completesOnView = validateCompletesOn(pageConfig, fileRel, errors);
+				pages.push({
+					fileRel,
+					navIndex,
+					hasGradedQuiz: pageHasGradedQuiz,
+					hasQuiz: !!pageConfig?.quiz,
+					completesOnView
+				});
 				validateAssetRefs(content, fileRel, assetsDir, warnings, assetExistsCache);
 			}
 		}
@@ -597,7 +641,8 @@ function validatePages(pagesDir, assetsDir, projectRoot) {
 		warnings,
 		totalPages,
 		totalQuizzes,
-		hasGradedQuiz
+		hasGradedQuiz,
+		pages
 	};
 }
 function validateMetaFile(metaPath, parentRel, errors) {
@@ -624,6 +669,12 @@ function validatePageConfig(content, fileRel, errors) {
 	if (result.kind === "invalid") errors.push(`${fileRel}: pageConfig must be a static object literal (no variables, function calls, or computed values)`);
 	return null;
 }
+function validateCompletesOn(pageConfig, fileRel, errors) {
+	if (!pageConfig || pageConfig.completesOn === void 0) return false;
+	if (pageConfig.completesOn === "view") return true;
+	errors.push(`${fileRel}: pageConfig.completesOn must be "view", got ${JSON.stringify(pageConfig.completesOn)}`);
+	return false;
+}
 function validateQuizConfig(quiz, fileRel, errors) {
 	if (!quiz || typeof quiz !== "object") return;
 	const cfg = quiz;
@@ -655,6 +706,19 @@ function validateAssetRefs(content, fileRel, assetsDir, warnings, existsCache) {
 }
 function crossValidate(config, pageResults, errors, warnings) {
 	if (config.completion?.mode === "quiz" && !pageResults.hasGradedQuiz) errors.push("completion.mode is \"quiz\" but no pages have quiz config with graded: true");
+	const isManual = config.completion?.mode === "manual";
+	const completesOnPages = pageResults.pages.filter((p) => p.completesOnView);
+	if (isManual && config.completion?.trigger === "page" && completesOnPages.length === 0) errors.push("completion.mode is \"manual\" with trigger: \"page\", but no page declares pageConfig.completesOn: \"view\". Either add a completesOn page or remove the trigger field to drop the static check.");
+	if (isManual) {
+		for (const page of pageResults.pages) if (page.hasGradedQuiz) warnings.push(`${page.fileRel}: quiz.graded is true under completion.mode: "manual". The score will be reported to the LMS for transcripts, but it will not drive completion or success status — \`markComplete()\` / completesOn does. If that's not what you want, set graded: false or change completion.mode.`);
+	}
+	if (isManual && config.completion?.percentageThreshold !== void 0) warnings.push("course.config.js: \"completion.percentageThreshold\" is ignored under completion.mode: \"manual\"");
+	if (!isManual) for (const page of completesOnPages) warnings.push(`${page.fileRel}: pageConfig.completesOn is ignored — completion.mode is "${config.completion?.mode ?? "percentage"}"`);
+	for (const page of pageResults.pages) if (page.completesOnView && page.hasQuiz) warnings.push(`${page.fileRel}: completion fires on view, before the quiz can be answered — likely a mistake`);
+	if (isManual) {
+		const firstPage = pageResults.pages.find((p) => p.navIndex === 0);
+		if (firstPage?.completesOnView) warnings.push(`${firstPage.fileRel}: pageConfig.completesOn: "view" is on the first page — the course will complete immediately on launch, before the learner sees any other content.`);
+	}
 	if (config.export?.standard === "scorm12") {
 		let visitedChars = 0;
 		for (let i = 0; i < pageResults.totalPages; i++) visitedChars += String(i).length + 1;
@@ -1049,6 +1113,19 @@ mount(App, {
 }
 const VIRTUAL_CONFIG_ID = "virtual:tessera-config";
 const RESOLVED_CONFIG_ID = "\0" + VIRTUAL_CONFIG_ID;
+function completionDefaults(mode) {
+	if (mode === "manual") return {
+		completion: { mode: "manual" },
+		passingScore: 0
+	};
+	return {
+		completion: {
+			mode: "percentage",
+			percentageThreshold: 100
+		},
+		passingScore: 70
+	};
+}
 function tesseraConfigPlugin() {
 	let projectRoot;
 	return {
@@ -1078,6 +1155,7 @@ function tesseraConfigPlugin() {
 						userConfig = JSON5.parse(objectStr);
 					} catch {}
 				}
+				const { completion, passingScore } = completionDefaults(userConfig.completion?.mode);
 				const merged = {
 					title: userConfig.title || "Untitled Course",
 					...userConfig,
@@ -1086,12 +1164,11 @@ function tesseraConfigPlugin() {
 						...userConfig.navigation
 					},
 					completion: {
-						mode: "percentage",
-						percentageThreshold: 100,
+						...completion,
 						...userConfig.completion
 					},
 					scoring: {
-						passingScore: 70,
+						passingScore,
 						...userConfig.scoring
 					},
 					export: {