tessera-learn 0.0.3 → 0.0.5

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.
@@ -878,13 +983,14 @@ The runtime translates author intent (page visits, quiz scores, completion, pers
 
 | Runtime event | SCORM 1.2 | SCORM 2004 4th | cmi5 |
 |---------------|-----------|----------------|------|
-| Session start | `LMSInitialize("")`; read `cmi.suspend_data` and `cmi.interactions._count` | `Initialize("")`; read `cmi.suspend_data` and `cmi.interactions._count` | `POST` cmi5 `fetch` URL → token; build publisher; `GET` State API; send **Initialized** statement |
+| Session start | `LMSInitialize("")`; read `cmi.suspend_data` and `cmi.interactions._count` | `Initialize("")`; read `cmi.suspend_data` and `cmi.interactions._count` | `POST` cmi5 `fetch` URL → token; `GET` `LMS.LaunchData` State (§10, → session id + Publisher Activity + launchMode + returnURL + masteryScore + moveOn); `GET` `cmi5LearnerPreferences` Agent Profile (§11); build publisher; send **Initialized**; `GET` `tessera-state` for resume |
 | 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) |
+| 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` and `result.duration` (one-shot per session). cmi5 §9.5.1 forbids `score` on Completed — the score rides on the subsequent **Passed**/**Failed** instead. |
+| 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) |
+| Author exit / unload | `LMSSetValue("cmi.core.exit", "suspend"\|"")`, `LMSCommit("")`, `LMSFinish("")` (queue drained synchronously) | `SetValue("cmi.exit", "suspend"\|"normal"\|...)`, `Commit("")`, `Terminate("")` (queue drained synchronously) | **Terminated** (always last on the wire, cmi5 §9.3.6). Explicit-exit path: `adapter.exit()` drains the queue then redirects to `returnURL` (§10.2.6). No Suspended verb — incomplete exit is signalled by Terminated without a preceding Completed; the LMS handles Abandoned and resume on next launch. |
 | Learner identity (xAPI actor synthesis) | `cmi.core.student_id` + `cmi.core.student_name` | `cmi.learner_id` + `cmi.learner_name` | Launch-supplied actor JSON (Identified Agent) |
 | Persistence cap | ~4096 chars per spec; many LMSes allow more, but plan for 4 KB | 64000 chars per spec | LRS-defined (typically unbounded for State API documents) |
 | Score scale exposed to LMS | `score.raw` only (0–100) | `score.raw` (0–100) **and** `score.scaled` (0–1) | `result.score.scaled` (0–1) |
@@ -921,15 +1027,25 @@ API discovery: `API_1484_11` via the same parent/opener walk.
 
 **Token fetch is single-use** (cmi5 §6.2). On failure, reload from the LMS to retry. The token is used as a `Basic` credential, not Bearer.
 
-**Lifecycle order.** **Initialized** → **Answered** (per question on submit) → **Completed** → **Passed** / **Failed** → **Suspended** (only if not Completed) → **Terminated** (always last, cmi5 §9.3.6). Completed / Passed / Failed are one-shot per session; once dispatched, the corresponding setter no-ops. A reloaded session may re-dispatch them, which is intended: each session sends its lifecycle exactly once.
+**Lifecycle order.** **Initialized** → **Answered** (per question on submit) → **Completed** → **Passed** / **Failed** → **Terminated** (always last, cmi5 §9.3.6). Completed / Passed / Failed are one-shot per session; once dispatched, the corresponding setter no-ops. A reloaded session may re-dispatch them, which is intended: each session sends its lifecycle exactly once. **Satisfied** and **Suspended** are not emitted by the AU — Satisfied is LMS-only (§9.3.9), and Suspended isn't a cmi5 verb (§9.3 enumerates nine; the LMS handles Abandoned / resume on relaunch).
+
+**Required result fields.** Completed: `completion: true`, `duration` (no `score` — §9.5.1 forbids it). Passed: `success: true`, `duration`, `result.score.scaled` when known (§9.3.4 requires `scaled >= masteryScore` when present). Failed: `success: false`, `duration`, `result.score.scaled` when known (§9.3.5 requires `scaled < masteryScore` when present). Terminated: `duration` (§9.5.4.1). On contradiction the verb is preserved and the score is dropped with a console warning.
+
+**Context per Defined Statement.** Categories: `cmi5` Category Activity on every Defined Statement (§9.6.2.1); plus `moveOn` Category on Completed / Passed / Failed (§9.6.2.2). Extensions: `sessionid` (§9.6.3.1) on every statement (Defined and Allowed) — value sourced from `LMS.LaunchData.contextTemplate` when supplied, else minted UUID. `masteryScore` extension on Passed / Failed only (§9.6.3.2). The full `contextTemplate` from `LMS.LaunchData` is merged in (§9.6.2 makes it the AU's base context; §10.2.1 says AU MUST NOT overwrite template values, so the AU's categories are concatenated and deduped against the template's, never replacing them).
+
+**`LMS.LaunchData` (§10).** Fetched once at init from the State API under `stateId='LMS.LaunchData'`. The AU reads `contextTemplate`, `launchMode`, `returnURL`, `launchParameters`, `masteryScore`, and `moveOn` from it. LaunchData values override anything parsed from the launch URL (§10.2.4 makes LaunchData authoritative). When the document is absent, statements ship without the LMS-supplied Publisher Activity and may be rejected by strict LRSes — a console warning fires.
+
+**Learner Preferences (§11).** `cmi5LearnerPreferences` from the Agent Profile API, fetched *before* Initialized — strict LRSes (SCORM Cloud) track that the GET happened and reject Initialized otherwise. A 404 here is normal (no preferences set); only the GET itself is required. Exposed to author code via `adapter.getLearnerPreferences()`.
+
+**Launch mode (§10.2.2).** "Normal" launches emit the full lifecycle. "Browse" and "Review" launches emit only Initialized and Terminated — every other Defined Statement is silently suppressed. Exposed via `adapter.getLaunchMode()`.
 
-**Required result fields.** Completed: `completion: true`, `duration`. Passed/Failed: `success`, `duration`. Terminated: `duration` (§9.5.4.1). All include `result.score.scaled` when a score is known.
+**Return URL (§10.2.6).** `adapter.exit()` is the explicit-exit path: calls `terminate()`, awaits the publisher queue so Terminated lands before navigation, then `window.location.assign(returnURL)`. The page-unload `terminate()` path can't redirect (the browser is already navigating). Bare `getReturnURL()` is available for authors who want to inspect the URL without triggering exit.
 
-**Sessionid extension.** `cmi5Mode` injects the spec-required `sessionid` context extension on every statement.
+**State persistence.** `tessera-state` document via the State API, keyed by `activityId` + `agent` + `registration?` + `stateId='tessera-state'` (distinct from the LMS-owned `LMS.LaunchData` and `cmi5LearnerPreferences` documents). Writes chain onto the publisher's queue so the suspend payload lands before Terminated.
 
-**State persistence.** `tessera-state` document via the State API, keyed by `activityId` + `agent` + `registration?` + `stateId='tessera-state'`. Writes chain onto the publisher's queue so the suspend payload lands before Terminated.
+**Manifest (`cmi5.xml`).** Generated by the plugin: course id + AU id are stable URNs derived from `config.title` (`urn:tessera:{course,au}:<hex>`). `<au>` carries `launchMethod="AnyWindow"` (CourseStructure XSD requires it), `moveOn` (`Completed` for percentage/manual, `CompletedAndPassed` for quiz mode), and `masteryScore` (rounded to 4 decimal places per §10.2.4). The `<url>` is a child element of `<au>`, not an attribute.
 
-**Not implemented.** No multi-AU courses (one course = one AU in v1). No **Waived** or **Abandoned** verbs. No mid-session actor refresh. No `MoveOn` criterion in `cmi5.xml`: completion is decided runtime-side; the LMS evaluates MoveOn against the verbs the runtime *does* emit.
+**Not implemented.** No multi-AU courses (one course = one AU in v1). No **Waived** or **Abandoned** verbs (LMS-only). No mid-session actor refresh.
 
 **Local testing.** Upload `dist/*-cmi5.zip` to SCORM Cloud and use the cmi5 dispatch URL it generates, the closest free equivalent to a real LMS launch.
 

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;
@@ -768,16 +832,17 @@ function generateCMI5Xml(config) {
 	const description = escapeXml(config.description || "");
 	const courseId = stableUrn("course", `tessera-course:${config.title || ""}`);
 	const auId = stableUrn("au", `tessera-au:${config.title || ""}`);
-	const masteryScore = (config.scoring?.passingScore ?? 70) / 100;
+	const masteryScore = Number(((config.scoring?.passingScore ?? 70) / 100).toFixed(4));
 	return `<?xml version="1.0" encoding="UTF-8"?>
 <courseStructure xmlns="https://w3id.org/xapi/profiles/cmi5/v1/CourseStructure.xsd">
   <course id="${courseId}">
     <title><langstring lang="en-US">${title}</langstring></title>
     <description><langstring lang="en-US">${description}</langstring></description>
   </course>
-  <au id="${auId}" url="index.html" moveOn="${config.completion?.mode === "quiz" ? "CompletedAndPassed" : "Completed"}" masteryScore="${masteryScore}">
+  <au id="${auId}" launchMethod="AnyWindow" moveOn="${config.completion?.mode === "quiz" ? "CompletedAndPassed" : "Completed"}" masteryScore="${masteryScore}">
     <title><langstring lang="en-US">${title}</langstring></title>
     <description><langstring lang="en-US">${description}</langstring></description>
+    <url>index.html</url>
   </au>
 </courseStructure>`;
 }
@@ -1049,6 +1114,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 +1156,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 +1165,11 @@ function tesseraConfigPlugin() {
 						...userConfig.navigation
 					},
 					completion: {
-						mode: "percentage",
-						percentageThreshold: 100,
+						...completion,
 						...userConfig.completion
 					},
 					scoring: {
-						passingScore: 70,
+						passingScore,
 						...userConfig.scoring
 					},
 					export: {