@lessonkit/lxpack 1.1.0 → 1.3.0

package/dist/index.cjs

@@ -61,97 +61,79 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/validateDescriptor.ts
+// src/descriptor/normalize.ts
 var import_core = require("@lessonkit/core");
-
-// src/spaPath.ts
-var import_node_fs = require("fs");
-var import_node_path = require("path");
-function resolveComparablePath(p) {
-  if (/^[a-zA-Z]:[/\\]/.test(p)) {
-    return import_node_path.win32.resolve(p);
-  }
-  return (0, import_node_path.resolve)(p);
-}
-function isSafeRelativeSpaPath(spaPath) {
-  if (!spaPath.length || spaPath.includes("\0")) return false;
-  if (spaPath.startsWith("/") || spaPath.startsWith("\\")) return false;
-  if (/^[a-zA-Z]:/.test(spaPath)) return false;
-  if (spaPath === "." || spaPath === "./") return false;
-  const segments = spaPath.split(/[/\\]/).filter((s) => s.length > 0 && s !== ".");
-  if (segments.some((s) => s === "..")) return false;
-  return segments.length > 0;
-}
-function assertResolvedPathUnderRoot(root, target) {
-  const rootResolved = resolveComparablePath(root);
-  const targetResolved = resolveComparablePath(target);
-  const prefix = rootResolved.endsWith(import_node_path.sep) ? rootResolved : rootResolved + import_node_path.sep;
-  const win32Prefix = rootResolved.endsWith(import_node_path.win32.sep) ? rootResolved : rootResolved + import_node_path.win32.sep;
-  if (targetResolved !== rootResolved && !targetResolved.startsWith(prefix) && /* v8 ignore next */
-  !targetResolved.startsWith(win32Prefix)) {
-    throw new Error(`unsafe path escapes project root: ${target}`);
-  }
-}
-function assertRealPathUnderRoot(root, target) {
-  const rootResolved = resolveComparablePath(root);
-  const targetResolved = resolveComparablePath(target);
-  let rootReal;
-  try {
-    rootReal = (0, import_node_fs.realpathSync)(rootResolved);
-  } catch {
-    rootReal = rootResolved;
-  }
-  let targetCheck;
-  try {
-    targetCheck = (0, import_node_fs.realpathSync)(targetResolved);
-  } catch {
-    const rel = (0, import_node_path.relative)(rootResolved, targetResolved);
-    if (rel.startsWith("..") || rel.includes(`..${import_node_path.sep}`)) {
-      throw new Error(`unsafe path escapes project root: ${target}`);
-    }
-    targetCheck = (0, import_node_path.resolve)(rootReal, rel);
-  }
-  assertResolvedPathUnderRoot(rootReal, targetCheck);
-}
-function normalizePathForComparison(p) {
-  const resolved = resolveComparablePath(p);
-  return /^[a-zA-Z]:[/\\]/.test(resolved) ? resolved.toLowerCase() : resolved;
-}
-function relativePathUnderRoot(root, target) {
-  const rootResolved = normalizePathForComparison(root);
-  const targetResolved = normalizePathForComparison(target);
-  if (/^[a-zA-Z]:[/\\]/.test(rootResolved)) {
-    return import_node_path.win32.relative(rootResolved, targetResolved);
-  }
-  return (0, import_node_path.relative)(rootResolved, targetResolved);
-}
-function isResolvedPathUnderRoot(root, target) {
-  const rootResolved = normalizePathForComparison(root);
-  const targetResolved = normalizePathForComparison(target);
-  if (targetResolved === rootResolved) return true;
-  const rel = relativePathUnderRoot(root, target);
-  if (!rel) return true;
-  return !rel.startsWith("..") && !(0, import_node_path.isAbsolute)(rel);
-}
-
-// src/theme.ts
-var import_themes = require("@lessonkit/themes");
-function themeToLxpackRuntime(input) {
-  const theme = input.theme ?? (0, import_themes.getPresetTheme)(input.preset ?? "default");
-  const raw = (0, import_themes.themeToCssVariables)(theme);
-  const cssVariables = {};
-  for (const [key, value] of Object.entries(raw)) {
-    cssVariables[key] = String(value);
-  }
+function normalizeDescriptor(input) {
+  const course = (0, import_core.validateId)(input.courseId, "courseId");
+  if (!course.ok) throw new Error("normalizeDescriptor called with invalid courseId");
   return {
-    theme: theme.name,
-    cssVariables
+    ...input,
+    courseId: course.id,
+    title: input.title.trim(),
+    version: input.version?.trim() || void 0,
+    spaLessonId: input.spaLessonId?.trim() || void 0,
+    lessons: input.lessons.map((lesson) => {
+      const idResult = (0, import_core.validateId)(lesson.id, "lessonId");
+      if (!idResult.ok) throw new Error("normalizeDescriptor called with invalid lesson id");
+      return {
+        ...lesson,
+        id: idResult.id,
+        title: lesson.title.trim(),
+        spaPath: lesson.spaPath?.trim() || void 0
+      };
+    }),
+    assessments: input.assessments?.map((assessment) => {
+      const check = (0, import_core.validateId)(assessment.checkId, "checkId");
+      if (!check.ok) throw new Error("normalizeDescriptor called with invalid checkId");
+      const question = assessment.question.trim();
+      if (assessment.kind === "trueFalse") {
+        return { ...assessment, checkId: check.id, question };
+      }
+      if (assessment.kind === "fillInBlanks") {
+        return {
+          ...assessment,
+          checkId: check.id,
+          question,
+          template: assessment.template.trim(),
+          blanks: assessment.blanks?.map((b) => ({
+            id: b.id.trim(),
+            answer: b.answer.trim()
+          }))
+        };
+      }
+      if (assessment.kind === "findHotspot") {
+        return {
+          ...assessment,
+          checkId: check.id,
+          question,
+          src: assessment.src.trim(),
+          alt: assessment.alt.trim(),
+          correctTargetId: assessment.correctTargetId.trim()
+        };
+      }
+      if (assessment.kind === "findMultipleHotspots") {
+        return {
+          ...assessment,
+          checkId: check.id,
+          question,
+          src: assessment.src.trim(),
+          alt: assessment.alt.trim(),
+          correctTargetIds: assessment.correctTargetIds.map((id) => id.trim()).filter((id) => id.length > 0)
+        };
+      }
+      const mcq = assessment;
+      return {
+        ...mcq,
+        checkId: check.id,
+        question,
+        choices: mcq.choices.map((c) => c.trim()).filter((c) => c.length > 0),
+        answer: mcq.answer.trim()
+      };
+    })
   };
 }
 
-// src/validateDescriptor.ts
-var VALID_LAYOUTS = ["single-spa", "per-lesson-spa"];
-var VALID_THEME_PRESETS = ["default", "light", "dark", "brand"];
+// src/descriptor/parseInput.ts
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -193,6 +175,32 @@ function parseAssessmentDescriptor(raw) {
       })) : void 0
     };
   }
+  if (kind === "findHotspot") {
+    return {
+      kind: "findHotspot",
+      ...base,
+      src: typeof raw.src === "string" ? raw.src : "",
+      alt: typeof raw.alt === "string" ? raw.alt : "",
+      correctTargetId: typeof raw.correctTargetId === "string" ? raw.correctTargetId : ""
+    };
+  }
+  if (kind === "findMultipleHotspots") {
+    return {
+      kind: "findMultipleHotspots",
+      ...base,
+      src: typeof raw.src === "string" ? raw.src : "",
+      alt: typeof raw.alt === "string" ? raw.alt : "",
+      correctTargetIds: Array.isArray(raw.correctTargetIds) ? raw.correctTargetIds.filter((id) => typeof id === "string") : []
+    };
+  }
+  if (typeof kind === "string" && kind !== "mcq" && kind !== "trueFalse" && kind !== "fillInBlanks" && kind !== "findHotspot" && kind !== "findMultipleHotspots") {
+    return {
+      kind,
+      ...base,
+      choices: [],
+      answer: ""
+    };
+  }
   return {
     kind: kind === "mcq" ? "mcq" : void 0,
     ...base,
@@ -239,82 +247,245 @@ function parseCourseDescriptorInput(input) {
     spaLessonId: typeof input.spaLessonId === "string" ? input.spaLessonId : void 0
   };
 }
-function normalizeDescriptor(input) {
-  const course = (0, import_core.validateId)(input.courseId, "courseId");
-  if (!course.ok) throw new Error("normalizeDescriptor called with invalid courseId");
-  return {
-    ...input,
-    courseId: course.id,
-    title: input.title.trim(),
-    version: input.version?.trim() || void 0,
-    spaLessonId: input.spaLessonId?.trim() || void 0,
-    lessons: input.lessons.map((lesson) => {
-      const idResult = (0, import_core.validateId)(lesson.id, "lessonId");
-      if (!idResult.ok) throw new Error("normalizeDescriptor called with invalid lesson id");
-      return {
-        ...lesson,
-        id: idResult.id,
-        title: lesson.title.trim(),
-        spaPath: lesson.spaPath?.trim() || void 0
-      };
-    }),
-    assessments: input.assessments?.map((assessment) => {
-      const check = (0, import_core.validateId)(assessment.checkId, "checkId");
-      if (!check.ok) throw new Error("normalizeDescriptor called with invalid checkId");
-      const question = assessment.question.trim();
-      if (assessment.kind === "trueFalse") {
-        return { ...assessment, checkId: check.id, question };
-      }
-      if (assessment.kind === "fillInBlanks") {
-        return {
-          ...assessment,
-          checkId: check.id,
-          question,
-          template: assessment.template.trim(),
-          blanks: assessment.blanks?.map((b) => ({
-            id: b.id.trim(),
-            answer: b.answer.trim()
-          }))
-        };
+
+// src/descriptor/validateCourse.ts
+var import_core3 = require("@lessonkit/core");
+var import_themes2 = require("@lessonkit/themes");
+
+// src/spaPath.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+function resolveComparablePath(p) {
+  if (/^[a-zA-Z]:[/\\]/.test(p)) {
+    return import_node_path.win32.resolve(p);
+  }
+  return (0, import_node_path.resolve)(p);
+}
+function isSafeRelativeSpaPath(spaPath) {
+  if (!spaPath.length || spaPath.includes("\0")) return false;
+  if (spaPath.startsWith("/") || spaPath.startsWith("\\")) return false;
+  if (/^[a-zA-Z]:/.test(spaPath)) return false;
+  if (spaPath === "." || spaPath === "./") return false;
+  const segments = spaPath.split(/[/\\]/).filter((s) => s.length > 0 && s !== ".");
+  if (segments.some((s) => s === "..")) return false;
+  return segments.length > 0;
+}
+function assertResolvedPathUnderRoot(root, target) {
+  const rootResolved = resolveComparablePath(root);
+  const targetResolved = resolveComparablePath(target);
+  const prefix = rootResolved.endsWith(import_node_path.sep) ? rootResolved : rootResolved + import_node_path.sep;
+  const win32Prefix = rootResolved.endsWith(import_node_path.win32.sep) ? rootResolved : rootResolved + import_node_path.win32.sep;
+  if (targetResolved !== rootResolved && !targetResolved.startsWith(prefix) && /* v8 ignore next */
+  !targetResolved.startsWith(win32Prefix)) {
+    throw new Error(`unsafe path escapes project root: ${target}`);
+  }
+}
+function resolveExistingPathUnderRoot(rootReal, rootResolved, targetResolved) {
+  const rel = (0, import_node_path.relative)(rootResolved, targetResolved);
+  if (rel.startsWith("..") || rel.includes(`..${import_node_path.sep}`)) {
+    throw new Error(`unsafe path escapes project root: ${targetResolved}`);
+  }
+  const segments = rel.split(/[/\\]/).filter((s) => s.length > 0 && s !== ".");
+  let current = rootReal;
+  for (const segment of segments) {
+    const next = (0, import_node_path.join)(current, segment);
+    if ((0, import_node_fs.existsSync)(next)) {
+      try {
+        current = (0, import_node_fs.realpathSync)(next);
+      } catch {
+        current = next;
       }
-      return {
-        ...assessment,
-        checkId: check.id,
-        question,
-        choices: assessment.choices.map((c) => c.trim()).filter((c) => c.length > 0),
-        answer: assessment.answer.trim()
-      };
-    })
+    } else {
+      current = next;
+    }
+    assertResolvedPathUnderRoot(rootReal, current);
+  }
+  return current;
+}
+function assertRealPathUnderRoot(root, target) {
+  const rootResolved = resolveComparablePath(root);
+  const targetResolved = resolveComparablePath(target);
+  let rootReal;
+  try {
+    rootReal = (0, import_node_fs.realpathSync)(rootResolved);
+  } catch {
+    rootReal = rootResolved;
+  }
+  try {
+    const targetCheck = (0, import_node_fs.realpathSync)(targetResolved);
+    assertResolvedPathUnderRoot(rootReal, targetCheck);
+  } catch {
+    resolveExistingPathUnderRoot(rootReal, rootResolved, targetResolved);
+  }
+}
+function normalizePathForComparison(p) {
+  const resolved = resolveComparablePath(p);
+  return /^[a-zA-Z]:[/\\]/.test(resolved) ? resolved.toLowerCase() : resolved;
+}
+function relativePathUnderRoot(root, target) {
+  const rootResolved = normalizePathForComparison(root);
+  const targetResolved = normalizePathForComparison(target);
+  if (/^[a-zA-Z]:[/\\]/.test(rootResolved)) {
+    return import_node_path.win32.relative(rootResolved, targetResolved);
+  }
+  return (0, import_node_path.relative)(rootResolved, targetResolved);
+}
+function isResolvedPathUnderRoot(root, target) {
+  const rootResolved = normalizePathForComparison(root);
+  const targetResolved = normalizePathForComparison(target);
+  if (targetResolved === rootResolved) return true;
+  const rel = relativePathUnderRoot(root, target);
+  if (!rel) return true;
+  return !rel.startsWith("..") && !(0, import_node_path.isAbsolute)(rel);
+}
+
+// src/theme.ts
+var import_themes = require("@lessonkit/themes");
+function themeToLxpackRuntime(input) {
+  const theme = input.theme ?? (0, import_themes.getPresetTheme)(input.preset ?? "default");
+  const raw = (0, import_themes.themeToCssVariables)(theme);
+  const cssVariables = {};
+  for (const [key, value] of Object.entries(raw)) {
+    cssVariables[key] = String(value);
+  }
+  return {
+    theme: theme.name,
+    cssVariables
   };
 }
-function validateDescriptor(input) {
-  const parsed = parseCourseDescriptorInput(input);
-  if (parsed === null) {
-    return { ok: false, issues: [{ path: "course", message: "must be an object" }] };
+
+// src/descriptor/validateAssessments.ts
+var import_core2 = require("@lessonkit/core");
+var validateMcqLike = (assessment, path, issues) => {
+  if (!("choices" in assessment) || !Array.isArray(assessment.choices)) {
+    issues.push({ path: `${path}.choices`, message: "choices is required for mcq" });
+    return;
   }
-  return validateDescriptorParsed(parsed);
+  if (!("answer" in assessment) || typeof assessment.answer !== "string") {
+    issues.push({ path: `${path}.answer`, message: "answer is required for mcq" });
+    return;
+  }
+  const trimmedChoices = assessment.choices.map((c) => c.trim()).filter((c) => c.length > 0);
+  if (!trimmedChoices.length) {
+    issues.push({ path: `${path}.choices`, message: "at least one non-empty choice is required" });
+  }
+  if (!assessment.answer.trim()) {
+    issues.push({ path: `${path}.answer`, message: "answer is required" });
+  } else if (trimmedChoices.length && !trimmedChoices.includes(assessment.answer.trim())) {
+    issues.push({ path: `${path}.answer`, message: "answer must match a choice" });
+  }
+};
+function countStarDelimitedBlanks(template) {
+  const matches = template.match(/\*[^*]+\*/g);
+  return matches?.length ?? 0;
 }
-function validateDescriptorForTarget(input, target) {
-  const result = validateDescriptor(input);
-  if (!result.ok || !target) return result;
-  if (target !== "xapi" && target !== "cmi5") return result;
-  const activityIri = result.descriptor.tracking?.xapi?.activityIri?.trim();
-  if (!activityIri) {
-    return {
-      ok: false,
-      issues: [
-        {
-          path: "course.tracking.xapi.activityIri",
-          message: "tracking.xapi.activityIri is required for xapi and cmi5 export targets"
-        }
-      ]
-    };
+function maxAchievableAssessmentScore(assessment) {
+  const kind = assessment.kind ?? "mcq";
+  if (kind === "fillInBlanks" && assessment.kind === "fillInBlanks") {
+    const explicit = assessment.blanks?.filter((b) => b?.id?.trim() && b?.answer?.trim()).length ?? 0;
+    if (explicit > 0) return explicit;
+    return countStarDelimitedBlanks(assessment.template ?? "");
   }
-  return result;
+  if (kind === "findMultipleHotspots" && assessment.kind === "findMultipleHotspots") {
+    return assessment.correctTargetIds?.map((id) => id.trim()).filter((id) => id.length > 0).length ?? 0;
+  }
+  return 1;
 }
-function validateDescriptorParsed(input) {
+var ASSESSMENT_VALIDATORS = {
+  mcq: validateMcqLike,
+  trueFalse: (assessment, path, issues) => {
+    if (assessment.kind === "trueFalse" && typeof assessment.answer !== "boolean") {
+      issues.push({ path: `${path}.answer`, message: "answer must be a boolean for trueFalse" });
+    }
+  },
+  fillInBlanks: (assessment, path, issues) => {
+    if (assessment.kind === "fillInBlanks" && !assessment.template?.trim()) {
+      issues.push({ path: `${path}.template`, message: "template is required for fillInBlanks" });
+    }
+  },
+  findHotspot: (assessment, path, issues) => {
+    if (assessment.kind !== "findHotspot") return;
+    if (!assessment.src?.trim()) {
+      issues.push({ path: `${path}.src`, message: "src is required for findHotspot" });
+    }
+    if (!assessment.alt?.trim()) {
+      issues.push({ path: `${path}.alt`, message: "alt is required for findHotspot" });
+    }
+    if (!assessment.correctTargetId?.trim()) {
+      issues.push({ path: `${path}.correctTargetId`, message: "correctTargetId is required for findHotspot" });
+    }
+  },
+  findMultipleHotspots: (assessment, path, issues) => {
+    if (assessment.kind !== "findMultipleHotspots") return;
+    if (!assessment.src?.trim()) {
+      issues.push({ path: `${path}.src`, message: "src is required for findMultipleHotspots" });
+    }
+    if (!assessment.alt?.trim()) {
+      issues.push({ path: `${path}.alt`, message: "alt is required for findMultipleHotspots" });
+    }
+    const ids = assessment.correctTargetIds?.map((id) => id.trim()).filter((id) => id.length > 0) ?? [];
+    if (!ids.length) {
+      issues.push({
+        path: `${path}.correctTargetIds`,
+        message: "at least one non-empty correctTargetId is required for findMultipleHotspots"
+      });
+    }
+  }
+};
+function validateAssessmentEntry(assessment, index, issues, checkIds) {
+  const path = `assessments[${index}]`;
+  const check = (0, import_core2.validateId)(assessment.checkId, `${path}.checkId`);
+  if (!check.ok) {
+    issues.push(...check.issues.map((i) => ({ path: i.path, message: i.message })));
+  } else if (checkIds.has(check.id)) {
+    issues.push({ path: `${path}.checkId`, message: "duplicate checkId" });
+  } else {
+    checkIds.add(check.id);
+  }
+  if (!assessment.question?.trim()) {
+    issues.push({ path: `${path}.question`, message: "question is required" });
+  }
+  const knownKinds = Object.keys(ASSESSMENT_VALIDATORS);
+  if (assessment.kind !== void 0 && assessment.kind !== "mcq" && !knownKinds.includes(assessment.kind)) {
+    issues.push({
+      path: `${path}.kind`,
+      message: `unknown kind; use one of: ${knownKinds.join(", ")}`
+    });
+    return;
+  }
+  const kind = assessment.kind ?? "mcq";
+  const validator = ASSESSMENT_VALIDATORS[kind];
+  if (!validator) {
+    issues.push({
+      path: `${path}.kind`,
+      message: `unknown kind; use one of: ${knownKinds.join(", ")}`
+    });
+    return;
+  }
+  validator(assessment, path, issues);
+  const passingScore = assessment.passingScore;
+  if (passingScore !== void 0 && !(Number.isFinite(passingScore) && passingScore > 0)) {
+    issues.push({
+      path: `${path}.passingScore`,
+      message: "passingScore must be greater than 0 (absolute point threshold)"
+    });
+  } else if (passingScore !== void 0) {
+    const maxAchievable = maxAchievableAssessmentScore(assessment);
+    if (maxAchievable > 0 && passingScore > maxAchievable) {
+      issues.push({
+        path: `${path}.passingScore`,
+        message: `passingScore cannot exceed achievable score (${maxAchievable}) for this assessment kind`
+      });
+    }
+  }
+}
+
+// src/descriptor/validateCourse.ts
+var VALID_LAYOUTS = ["single-spa", "per-lesson-spa"];
+var VALID_THEME_PRESETS = ["default", "light", "dark", "brand"];
+function validateCourseDescriptor(input) {
   const issues = [];
-  const course = (0, import_core.validateId)(input.courseId, "courseId");
+  const course = (0, import_core3.validateId)(input.courseId, "courseId");
   if (!course.ok) issues.push(...course.issues.map((i) => ({ path: i.path, message: i.message })));
   if (!input.title?.trim()) {
     issues.push({ path: "title", message: "title is required" });
@@ -339,13 +510,23 @@ function validateDescriptorParsed(input) {
     });
   }
   if (input.theme?.theme) {
-    try {
-      themeToLxpackRuntime({ preset: themePreset, theme: input.theme.theme });
-    } catch (err) {
-      issues.push({
-        path: "theme.theme",
-        message: err instanceof Error ? err.message : "invalid custom theme"
-      });
+    const themeResult = (0, import_themes2.validateTheme)(input.theme.theme);
+    if (!themeResult.ok) {
+      for (const issue of themeResult.issues) {
+        issues.push({
+          path: issue.path ? `theme.theme.${issue.path}` : "theme.theme",
+          message: issue.message
+        });
+      }
+    } else {
+      try {
+        themeToLxpackRuntime({ preset: themePreset, theme: themeResult.theme });
+      } catch (err) {
+        issues.push({
+          path: "theme.theme",
+          message: err instanceof Error ? err.message : "invalid custom theme"
+        });
+      }
     }
   }
   const completionThreshold = input.tracking?.completion?.threshold;
@@ -367,7 +548,7 @@ function validateDescriptorParsed(input) {
   const spaPaths = /* @__PURE__ */ new Set();
   for (const [index, lesson] of (input.lessons ?? []).entries()) {
     const path = `lessons[${index}]`;
-    const lessonResult = (0, import_core.validateId)(lesson.id, `${path}.id`);
+    const lessonResult = (0, import_core3.validateId)(lesson.id, `${path}.id`);
     if (!lessonResult.ok) {
       issues.push(...lessonResult.issues.map((i) => ({ path: i.path, message: i.message })));
     } else if (lessonIds.has(lessonResult.id)) {
@@ -395,68 +576,147 @@ function validateDescriptorParsed(input) {
       } else {
         spaPaths.add(spaPath);
       }
-    }
+    }
+  }
+  if (layout === "single-spa" && input.spaLessonId?.trim()) {
+    const spaId = input.spaLessonId.trim();
+    const spaResult = (0, import_core3.validateId)(spaId, "spaLessonId");
+    if (!spaResult.ok) {
+      issues.push(...spaResult.issues.map((i) => ({ path: i.path, message: i.message })));
+    } else if (!lessonIds.has(spaResult.id)) {
+      issues.push({
+        path: "spaLessonId",
+        message: "spaLessonId must match a lesson id in lessons"
+      });
+    }
+  }
+  const checkIds = /* @__PURE__ */ new Set();
+  for (const [index, assessment] of (input.assessments ?? []).entries()) {
+    validateAssessmentEntry(assessment, index, issues, checkIds);
+  }
+  return issues;
+}
+
+// src/assessments.ts
+function slugChoiceId(text, index) {
+  const base = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32);
+  const stem = base.length ? base : "choice";
+  return `${stem}-${index + 1}`;
+}
+function mcqToLxpack(assessment) {
+  const choices = assessment.choices.map((text, index) => {
+    const id = slugChoiceId(text, index);
+    return {
+      id,
+      text,
+      correct: text === assessment.answer
+    };
+  });
+  return {
+    id: assessment.checkId,
+    passingScore: assessment.passingScore ?? 1,
+    questions: [
+      {
+        id: "q1",
+        prompt: assessment.question,
+        choices
+      }
+    ]
+  };
+}
+function assessmentDescriptorToLxpack(assessment) {
+  const kind = assessment.kind ?? "mcq";
+  if (kind === "trueFalse" && assessment.kind === "trueFalse") {
+    const choices = ["True", "False"];
+    const answerText = assessment.answer ? "True" : "False";
+    return mcqToLxpack({
+      kind: "mcq",
+      checkId: assessment.checkId,
+      question: assessment.question,
+      choices,
+      answer: answerText,
+      passingScore: assessment.passingScore
+    });
   }
-  if (layout === "single-spa" && input.spaLessonId?.trim()) {
-    const spaId = input.spaLessonId.trim();
-    const spaResult = (0, import_core.validateId)(spaId, "spaLessonId");
-    if (!spaResult.ok) {
-      issues.push(...spaResult.issues.map((i) => ({ path: i.path, message: i.message })));
-    } else if (!lessonIds.has(spaResult.id)) {
+  if (kind === "fillInBlanks") {
+    return null;
+  }
+  if (kind === "findHotspot" && assessment.kind === "findHotspot") {
+    return mcqToLxpack({
+      kind: "mcq",
+      checkId: assessment.checkId,
+      question: assessment.question,
+      choices: [assessment.correctTargetId, "other"],
+      answer: assessment.correctTargetId,
+      passingScore: assessment.passingScore
+    });
+  }
+  if (kind === "findMultipleHotspots") {
+    return null;
+  }
+  if ("choices" in assessment && "answer" in assessment && typeof assessment.answer === "string") {
+    return mcqToLxpack(assessment);
+  }
+  return null;
+}
+function extractAssessments(descriptor) {
+  return (descriptor.assessments ?? []).map(assessmentDescriptorToLxpack).filter((a) => a !== null);
+}
+
+// src/descriptor/validateForTarget.ts
+var LMS_SHELL_TARGETS = /* @__PURE__ */ new Set([
+  "scorm12",
+  "scorm2004",
+  "standalone",
+  "xapi",
+  "cmi5"
+]);
+function validateDescriptorForExportTarget(descriptor, target) {
+  const issues = [];
+  if (target === "xapi" || target === "cmi5") {
+    const activityIri = descriptor.tracking?.xapi?.activityIri?.trim();
+    if (!activityIri) {
       issues.push({
-        path: "spaLessonId",
-        message: "spaLessonId must match a lesson id in lessons"
+        path: "course.tracking.xapi.activityIri",
+        message: "tracking.xapi.activityIri is required for xapi and cmi5 export targets"
       });
     }
   }
-  const checkIds = /* @__PURE__ */ new Set();
-  for (const [index, assessment] of (input.assessments ?? []).entries()) {
-    const path = `assessments[${index}]`;
-    const check = (0, import_core.validateId)(assessment.checkId, `${path}.checkId`);
-    if (!check.ok) {
-      issues.push(...check.issues.map((i) => ({ path: i.path, message: i.message })));
-    } else if (checkIds.has(check.id)) {
-      issues.push({ path: `${path}.checkId`, message: "duplicate checkId" });
-    } else {
-      checkIds.add(check.id);
-    }
-    if (!assessment.question?.trim()) {
-      issues.push({ path: `${path}.question`, message: "question is required" });
-    }
-    const kind = assessment.kind ?? "mcq";
-    if (kind === "trueFalse" && assessment.kind === "trueFalse") {
-      if (typeof assessment.answer !== "boolean") {
-        issues.push({ path: `${path}.answer`, message: "answer must be a boolean for trueFalse" });
-      }
-    } else if (kind === "fillInBlanks" && assessment.kind === "fillInBlanks") {
-      if (!assessment.template?.trim()) {
-        issues.push({ path: `${path}.template`, message: "template is required for fillInBlanks" });
-      }
-    } else if ("choices" in assessment && "answer" in assessment && typeof assessment.answer === "string") {
-      const trimmedChoices = assessment.choices.map((c) => c.trim()).filter((c) => c.length > 0);
-      if (!trimmedChoices.length) {
+  if (LMS_SHELL_TARGETS.has(target)) {
+    (descriptor.assessments ?? []).forEach((assessment, index) => {
+      if (assessmentDescriptorToLxpack(assessment) === null) {
         issues.push({
-          path: `${path}.choices`,
-          message: "at least one non-empty choice is required"
+          path: `assessments[${index}]`,
+          message: `assessment kind "${assessment.kind ?? "mcq"}" (checkId "${assessment.checkId}") is not injected into LMS shell quizzes for target "${target}"`
         });
       }
-      if (!assessment.answer.trim()) {
-        issues.push({ path: `${path}.answer`, message: "answer is required" });
-      } else if (trimmedChoices.length && !trimmedChoices.includes(assessment.answer.trim())) {
-        issues.push({ path: `${path}.answer`, message: "answer must match a choice" });
-      }
-    }
-    const passingScore = assessment.passingScore;
-    if (passingScore !== void 0 && !(Number.isFinite(passingScore) && passingScore > 0)) {
-      issues.push({
-        path: `${path}.passingScore`,
-        message: "passingScore must be greater than 0 (absolute point threshold)"
-      });
-    }
+    });
   }
+  return issues;
+}
+
+// src/validateDescriptor.ts
+function validateDescriptorParsed(input) {
+  const issues = validateCourseDescriptor(input);
   if (issues.length) return { ok: false, issues };
   return { ok: true, descriptor: normalizeDescriptor(input) };
 }
+function validateDescriptor(input) {
+  const parsed = parseCourseDescriptorInput(input);
+  if (parsed === null) {
+    return { ok: false, issues: [{ path: "course", message: "must be an object" }] };
+  }
+  return validateDescriptorParsed(parsed);
+}
+function validateDescriptorForTarget(input, target) {
+  const result = validateDescriptor(input);
+  if (!result.ok || !target) return result;
+  const targetIssues = validateDescriptorForExportTarget(result.descriptor, target);
+  if (targetIssues.length) {
+    return { ok: false, issues: targetIssues };
+  }
+  return result;
+}
 
 // src/validateProjectPaths.ts
 var import_node_path2 = require("path");
@@ -511,69 +771,16 @@ function resolveSafePackageOutputOverride(projectRoot, override) {
 }
 
 // src/mapIds.ts
-var import_core2 = require("@lessonkit/core");
+var import_core4 = require("@lessonkit/core");
 function mapLessonkitIds(descriptor) {
-  const courseId = (0, import_core2.assertValidId)(descriptor.courseId, "courseId");
-  const lessonIds = descriptor.lessons.map((l) => (0, import_core2.assertValidId)(l.id, "lessonId"));
+  const courseId = (0, import_core4.assertValidId)(descriptor.courseId, "courseId");
+  const lessonIds = descriptor.lessons.map((l) => (0, import_core4.assertValidId)(l.id, "lessonId"));
   const checkIds = (descriptor.assessments ?? []).map(
-    (a) => (0, import_core2.assertValidId)(a.checkId, "checkId")
+    (a) => (0, import_core4.assertValidId)(a.checkId, "checkId")
   );
   return { courseId, lessonIds, checkIds };
 }
 
-// src/assessments.ts
-function slugChoiceId(text, index) {
-  const base = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32);
-  const stem = base.length ? base : "choice";
-  return `${stem}-${index + 1}`;
-}
-function mcqToLxpack(assessment) {
-  const choices = assessment.choices.map((text, index) => {
-    const id = slugChoiceId(text, index);
-    return {
-      id,
-      text,
-      correct: text === assessment.answer
-    };
-  });
-  return {
-    id: assessment.checkId,
-    passingScore: assessment.passingScore ?? 1,
-    questions: [
-      {
-        id: "q1",
-        prompt: assessment.question,
-        choices
-      }
-    ]
-  };
-}
-function assessmentDescriptorToLxpack(assessment) {
-  const kind = assessment.kind ?? "mcq";
-  if (kind === "trueFalse" && assessment.kind === "trueFalse") {
-    const choices = ["True", "False"];
-    const answerText = assessment.answer ? "True" : "False";
-    return mcqToLxpack({
-      kind: "mcq",
-      checkId: assessment.checkId,
-      question: assessment.question,
-      choices,
-      answer: answerText,
-      passingScore: assessment.passingScore
-    });
-  }
-  if (kind === "fillInBlanks") {
-    return null;
-  }
-  if ("choices" in assessment && "answer" in assessment && typeof assessment.answer === "string") {
-    return mcqToLxpack(assessment);
-  }
-  return null;
-}
-function extractAssessments(descriptor) {
-  return (descriptor.assessments ?? []).map(assessmentDescriptorToLxpack).filter((a) => a !== null);
-}
-
 // src/interchange.ts
 function mapDescriptorTracking(tracking) {
   if (!tracking) return void 0;
@@ -736,44 +943,71 @@ var import_node_path5 = require("path");
 function validatePackageInputs(options) {
   const { target, output, outputBaseDir } = options;
   const outDir = (0, import_node_path5.resolve)(options.outDir);
-  const projectRoot = options.projectRoot ? (0, import_node_path5.resolve)(options.projectRoot) : void 0;
-  if (projectRoot) {
-    try {
-      assertRealPathUnderRoot(projectRoot, outDir);
-    } catch (err) {
-      return {
-        ok: false,
-        courseDir: outDir,
-        target,
-        issues: [
-          {
-            path: "outDir",
-            message: (
-              /* v8 ignore next */
-              err instanceof Error ? err.message : String(err)
-            )
-          }
-        ]
-      };
-    }
+  if (!options.projectRoot) {
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      issues: [{ path: "projectRoot", message: "projectRoot is required for packageLessonkitCourse" }]
+    };
   }
-  if (outputBaseDir && !isSafeRelativeSpaPath(outputBaseDir)) {
+  const projectRoot = (0, import_node_path5.resolve)(options.projectRoot);
+  try {
+    assertRealPathUnderRoot(projectRoot, outDir);
+  } catch (err) {
     return {
       ok: false,
       courseDir: outDir,
       target,
-      issues: [{ path: "outputBaseDir", message: `unsafe outputBaseDir: ${outputBaseDir}` }]
+      issues: [
+        {
+          path: "outDir",
+          message: (
+            /* v8 ignore next */
+            err instanceof Error ? err.message : String(err)
+          )
+        }
+      ]
     };
   }
-  if (output && !projectRoot && !isSafeRelativeSpaPath(output)) {
+  if (outputBaseDir && !isSafeRelativeSpaPath(outputBaseDir)) {
     return {
       ok: false,
       courseDir: outDir,
       target,
-      issues: [{ path: "output", message: `unsafe output: ${output}` }]
+      issues: [{ path: "outputBaseDir", message: `unsafe outputBaseDir: ${outputBaseDir}` }]
     };
   }
-  if (projectRoot && outputBaseDir) {
+  if (output && !isSafeRelativeSpaPath(output)) {
+    if ((0, import_node_path5.isAbsolute)(output)) {
+      try {
+        assertRealPathUnderRoot(projectRoot, (0, import_node_path5.resolve)(output));
+      } catch (err) {
+        return {
+          ok: false,
+          courseDir: outDir,
+          target,
+          issues: [
+            {
+              path: "output",
+              message: (
+                /* v8 ignore next */
+                err instanceof Error ? err.message : `unsafe output: ${output}`
+              )
+            }
+          ]
+        };
+      }
+    } else {
+      return {
+        ok: false,
+        courseDir: outDir,
+        target,
+        issues: [{ path: "output", message: `unsafe output: ${output}` }]
+      };
+    }
+  }
+  if (outputBaseDir) {
     const resolvedOutputBase = (0, import_node_path5.resolve)(projectRoot, outputBaseDir);
     try {
       assertRealPathUnderRoot(projectRoot, resolvedOutputBase);
@@ -794,8 +1028,8 @@ function validatePackageInputs(options) {
       };
     }
   }
-  if (projectRoot && output) {
-    const resolvedOutput = (0, import_node_path5.resolve)(projectRoot, output);
+  if (output) {
+    const resolvedOutput = (0, import_node_path5.isAbsolute)(output) ? (0, import_node_path5.resolve)(output) : (0, import_node_path5.resolve)(projectRoot, output);
     try {
       assertRealPathUnderRoot(projectRoot, resolvedOutput);
     } catch (err) {
@@ -832,11 +1066,11 @@ function remapArtifactPaths(stagingRoot, outDir, artifactPath) {
   if (!artifactPath) return void 0;
   const resolved = resolveComparablePath(artifactPath);
   if (!isResolvedPathUnderRoot(stagingRoot, resolved)) {
-    return artifactPath;
+    throw new Error(`${artifactPath} is outside the staging directory`);
   }
   const rel = relativePathUnderRoot(stagingRoot, resolved);
   if (rel.startsWith("..") || (0, import_node_path5.isAbsolute)(rel)) {
-    return artifactPath;
+    throw new Error(`${artifactPath} is outside the staging directory`);
   }
   if (!rel) return outDir;
   if (/^[a-zA-Z]:[/\\]/.test(outDir)) {
@@ -867,6 +1101,68 @@ async function renameOrCopy(from, to) {
     await fsp.rm(from, { recursive: true, force: true });
   }
 }
+function promoteLockPath(outDir) {
+  const parent = (0, import_node_path6.dirname)(outDir);
+  const hash = (0, import_node_crypto.createHash)("sha256").update((0, import_node_path6.resolve)(outDir)).digest("hex").slice(0, 16);
+  return (0, import_node_path6.join)(parent, `.lk-promote-lock-${hash}`);
+}
+var STALE_LOCK_TTL_MS = 5 * 60 * 1e3;
+async function isStalePromoteLock(lockPath) {
+  try {
+    const stat2 = await fsp.stat(lockPath);
+    if (Date.now() - stat2.mtimeMs > STALE_LOCK_TTL_MS) return true;
+    const content = await fsp.readFile(lockPath, "utf8");
+    const pid = Number.parseInt(content.trim(), 10);
+    if (!Number.isFinite(pid) || pid <= 0) return true;
+    try {
+      process.kill(pid, 0);
+      return false;
+    } catch {
+      return true;
+    }
+  } catch {
+    return true;
+  }
+}
+async function withPromoteLock(outDir, fn) {
+  const lockPath = promoteLockPath(outDir);
+  await fsp.mkdir((0, import_node_path6.dirname)(outDir), { recursive: true });
+  let lockHandle;
+  for (let attempt = 0; attempt < 200; attempt++) {
+    try {
+      lockHandle = await fsp.open(lockPath, "wx");
+      await lockHandle.writeFile(`${process.pid}
+`, "utf8");
+      break;
+    } catch (err) {
+      const code = err && typeof err === "object" && "code" in err ? String(err.code) : "";
+      if (code !== "EEXIST") throw err;
+      if (await isStalePromoteLock(lockPath)) {
+        await fsp.rm(lockPath, { force: true }).catch(
+          /* v8 ignore next */
+          () => void 0
+        );
+        continue;
+      }
+      await new Promise((resolveWait) => setTimeout(resolveWait, 25));
+    }
+  }
+  if (!lockHandle) {
+    throw new Error(`[lessonkit/lxpack] timed out acquiring promote lock for ${outDir}`);
+  }
+  try {
+    return await fn();
+  } finally {
+    await lockHandle.close().catch(
+      /* v8 ignore next */
+      () => void 0
+    );
+    await fsp.rm(lockPath, { force: true }).catch(
+      /* v8 ignore next */
+      () => void 0
+    );
+  }
+}
 async function assertNoLegacyPromoteArtifacts(outDir) {
   const legacyTmp = `${outDir}.tmp-promote`;
   const legacyBak = `${outDir}.bak`;
@@ -880,45 +1176,57 @@ async function assertNoLegacyPromoteArtifacts(outDir) {
   }
 }
 async function promoteStagingToOutDir(stagingDir, outDir) {
-  await assertNoLegacyPromoteArtifacts(outDir);
-  const parent = (0, import_node_path6.dirname)(outDir);
-  const tmpPromote = await fsp.mkdtemp((0, import_node_path6.join)(parent, ".lk-promote-"));
-  await renameOrCopy(stagingDir, tmpPromote);
-  const hadOutDir = await pathExists(outDir);
-  const backup = hadOutDir ? await fsp.mkdtemp((0, import_node_path6.join)(parent, ".lk-backup-")) : void 0;
-  if (hadOutDir && backup) {
-    await renameOrCopy(outDir, backup);
-  }
-  try {
-    await renameOrCopy(tmpPromote, outDir);
-  } catch (promoteError) {
+  return withPromoteLock(outDir, async () => {
+    await assertNoLegacyPromoteArtifacts(outDir);
+    const parent = (0, import_node_path6.dirname)(outDir);
+    const tmpPromote = await fsp.mkdtemp((0, import_node_path6.join)(parent, ".lk-promote-"));
+    await renameOrCopy(stagingDir, tmpPromote);
+    const hadOutDir = await pathExists(outDir);
+    const backup = hadOutDir ? await fsp.mkdtemp((0, import_node_path6.join)(parent, ".lk-backup-")) : void 0;
     if (hadOutDir && backup) {
-      try {
-        await renameOrCopy(backup, outDir);
-      } catch (restoreError) {
-        const failedPromote2 = (0, import_node_path6.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
+      await renameOrCopy(outDir, backup);
+    }
+    try {
+      await renameOrCopy(tmpPromote, outDir);
+    } catch (promoteError) {
+      if (hadOutDir && backup) {
+        try {
+          await renameOrCopy(backup, outDir);
+        } catch (restoreError) {
+          const failedPromote2 = (0, import_node_path6.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
+          try {
+            await renameOrCopy(tmpPromote, failedPromote2);
+          } catch {
+            await fsp.rm(tmpPromote, { recursive: true, force: true }).catch(
+              /* v8 ignore next */
+              () => void 0
+            );
+          }
+          const promoteMsg = promoteError instanceof Error ? promoteError.message : String(promoteError);
+          const restoreMsg = restoreError instanceof Error ? restoreError.message : String(restoreError);
+          throw new Error(
+            `[lessonkit/lxpack] promote failed (${promoteMsg}) and could not restore ${outDir} (${restoreMsg}). Recovery: previous output may be in ${backup}; staged package may be in ${failedPromote2}.`
+          );
+        }
+      } else {
         try {
-          await renameOrCopy(tmpPromote, failedPromote2);
-        } catch {
+          await renameOrCopy(tmpPromote, stagingDir);
+        } catch (restoreError) {
+          console.warn(
+            `[lessonkit/lxpack] failed to restore ${stagingDir} after promote error:`,
+            restoreError instanceof Error ? restoreError.message : restoreError
+          );
           await fsp.rm(tmpPromote, { recursive: true, force: true }).catch(
             /* v8 ignore next */
             () => void 0
           );
         }
-        const promoteMsg = promoteError instanceof Error ? promoteError.message : String(promoteError);
-        const restoreMsg = restoreError instanceof Error ? restoreError.message : String(restoreError);
-        throw new Error(
-          `[lessonkit/lxpack] promote failed (${promoteMsg}) and could not restore ${outDir} (${restoreMsg}). Recovery: previous output may be in ${backup}; staged package may be in ${failedPromote2}.`
-        );
+        throw promoteError;
       }
-    } else {
+      const failedPromote = (0, import_node_path6.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
       try {
-        await renameOrCopy(tmpPromote, stagingDir);
-      } catch (restoreError) {
-        console.warn(
-          `[lessonkit/lxpack] failed to restore ${stagingDir} after promote error:`,
-          restoreError instanceof Error ? restoreError.message : restoreError
-        );
+        await renameOrCopy(tmpPromote, failedPromote);
+      } catch {
         await fsp.rm(tmpPromote, { recursive: true, force: true }).catch(
           /* v8 ignore next */
           () => void 0
@@ -926,23 +1234,13 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
       }
       throw promoteError;
     }
-    const failedPromote = (0, import_node_path6.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
-    try {
-      await renameOrCopy(tmpPromote, failedPromote);
-    } catch {
-      await fsp.rm(tmpPromote, { recursive: true, force: true }).catch(
+    if (backup) {
+      await fsp.rm(backup, { recursive: true, force: true }).catch(
         /* v8 ignore next */
         () => void 0
       );
     }
-    throw promoteError;
-  }
-  if (backup) {
-    await fsp.rm(backup, { recursive: true, force: true }).catch(
-      /* v8 ignore next */
-      () => void 0
-    );
-  }
+  });
 }
 
 // src/packaging/staging.ts
@@ -1015,6 +1313,15 @@ async function ensureOutDirParent(outDir) {
   await fsp2.mkdir((0, import_node_path7.dirname)(outDir), { recursive: true });
 }
 
+// src/packaging/issueSeverity.ts
+function isPackagingErrorIssue(issue) {
+  const severity = issue.severity?.toLowerCase();
+  return severity === "error" || severity === "fatal";
+}
+function findPackagingErrorIssues(issues) {
+  return (issues ?? []).filter(isPackagingErrorIssue);
+}
+
 // src/packageCourse.ts
 async function validateLessonkitProject(options) {
   return (0, import_api2.validateCourse)({
@@ -1064,6 +1371,18 @@ async function packageLessonkitCourse(options) {
     };
   }
   const descriptor = descriptorValidation.descriptor;
+  const nonInjectableAssessments = (descriptor.assessments ?? []).map((assessment, index) => ({ assessment, index })).filter(({ assessment }) => assessmentDescriptorToLxpack(assessment) === null);
+  if (nonInjectableAssessments.length > 0) {
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      issues: nonInjectableAssessments.map(({ assessment, index }) => ({
+        path: `assessments[${index}]`,
+        message: `assessment kind "${assessment.kind ?? "mcq"}" (checkId "${assessment.checkId}") is not injected into LMS shell quizzes for target "${target}"`
+      }))
+    };
+  }
   const staged = await buildStagingPackage({
     ...writeOpts,
     descriptor,
@@ -1088,6 +1407,25 @@ async function packageLessonkitCourse(options) {
     };
   }
   const { stagingDir, build } = staged;
+  const buildErrorIssues = findPackagingErrorIssues(build.issues);
+  if (buildErrorIssues.length > 0) {
+    await fsp3.rm(stagingDir, { recursive: true, force: true }).catch(
+      /* v8 ignore next */
+      () => void 0
+    );
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      validation: { ok: false, manifest: build.manifest, issues: build.issues },
+      build,
+      issues: build.issues.filter((i) => findPackagingErrorIssues([i]).length > 0).map((i) => ({
+        path: i.path ?? "build",
+        message: i.message,
+        severity: i.severity
+      }))
+    };
+  }
   const stagingRoot = await fsp3.realpath(stagingDir);
   const artifactIssues = [
     validateArtifactInStaging(stagingRoot, staged.outputPath, "outputPath"),
@@ -1118,6 +1456,10 @@ async function packageLessonkitCourse(options) {
     await ensureOutDirParent(outDir);
     await promoteStagingToOutDir(stagingDir, outDir);
   } catch (err) {
+    await fsp3.rm(stagingDir, { recursive: true, force: true }).catch(
+      /* v8 ignore next */
+      () => void 0
+    );
     return {
       ok: false,
       courseDir: outDir,