@lessonkit/lxpack 1.5.0 → 1.7.0

package/dist/index.cjs

@@ -31,22 +31,27 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   LESSONKIT_TELEMETRY_EVENTS: () => import_tracking_schema2.LESSONKIT_TELEMETRY_EVENTS,
+  assertSpaDistContentsSafe: () => assertSpaDistContentsSafe,
   assessmentDescriptorToLxpack: () => assessmentDescriptorToLxpack,
   buildLessonkitProject: () => buildLessonkitProject,
   buildStagingPackage: () => buildStagingPackage,
   descriptorToInterchange: () => descriptorToInterchange,
   ensureOutDirParent: () => ensureOutDirParent,
   escapeShellText: () => escapeShellText,
+  exportLkcourse: () => exportLkcourse,
   extractAssessments: () => extractAssessments,
-  lessonkitInterchangeSchema: () => import_validators2.lessonkitInterchangeSchema,
+  extractBlockTree: () => extractBlockTree,
+  importLkcourse: () => importLkcourse,
+  lessonkitInterchangeSchema: () => import_validators4.lessonkitInterchangeSchema,
   loadLessonkitManifestFromFile: () => loadLessonkitManifestFromFile,
   mapLessonkitIds: () => mapLessonkitIds,
   mapLessonkitTelemetryToBridgeAction: () => import_tracking_schema2.mapLessonkitTelemetryToBridgeAction,
   mapLessonkitTelemetryToLxpack: () => import_tracking_schema2.mapLessonkitTelemetryToLxpack,
-  materializeLessonkitProject: () => import_validators2.materializeLessonkitProject,
+  materializeLessonkitProject: () => import_validators4.materializeLessonkitProject,
   packageLessonkitCourse: () => packageLessonkitCourse,
-  parseLessonkitInterchange: () => import_validators2.parseLessonkitInterchange,
+  parseLessonkitInterchange: () => import_validators4.parseLessonkitInterchange,
   parseLessonkitManifest: () => parseLessonkitManifest,
+  parseLkcourseEnvelope: () => parseLkcourseEnvelope,
   promoteStagingToOutDir: () => promoteStagingToOutDir,
   remapArtifactPaths: () => remapArtifactPaths,
   resolveSafePackageOutputOverride: () => resolveSafePackageOutputOverride,
@@ -56,6 +61,9 @@ __export(index_exports, {
   validateDescriptor: () => validateDescriptor,
   validateDescriptorForTarget: () => validateDescriptorForTarget,
   validateLessonkitProject: () => validateLessonkitProject,
+  validateLkcourse: () => validateLkcourse,
+  validateLkcourseArchiveEntries: () => validateLkcourseArchiveEntries,
+  validateManifestName: () => validateManifestName,
   validatePackageInputs: () => validatePackageInputs,
   validateProjectPaths: () => validateProjectPaths,
   validateReactManifestParity: () => validateReactManifestParity,
@@ -123,13 +131,40 @@ function normalizeDescriptor(input) {
           correctTargetIds: assessment.correctTargetIds.map((id) => id.trim()).filter((id) => id.length > 0)
         };
       }
+      if (assessment.kind === "sortParagraphs") {
+        return {
+          ...assessment,
+          checkId: check.id,
+          question,
+          paragraphs: assessment.paragraphs.map((p) => p.trim()).filter((p) => p.length > 0),
+          correctOrder: [...assessment.correctOrder]
+        };
+      }
+      if (assessment.kind === "guessTheAnswer") {
+        return {
+          ...assessment,
+          checkId: check.id,
+          question,
+          answer: assessment.answer.trim()
+        };
+      }
+      if (assessment.kind === "multimediaChoice") {
+        return {
+          ...assessment,
+          checkId: check.id,
+          question,
+          choices: assessment.choices.map((c) => c.trim()).filter((c) => c.length > 0),
+          answer: assessment.answer.trim()
+        };
+      }
       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()
+        answer: mcq.answer.trim(),
+        answers: mcq.answers?.map((a) => a.trim()).filter((a) => a.length > 0)
       };
     })
   };
@@ -160,10 +195,18 @@ function parseAssessmentDescriptor(raw) {
   };
   const kind = raw.kind;
   if (kind === "trueFalse") {
+    let answer;
+    if (typeof raw.answer === "boolean") {
+      answer = raw.answer;
+    } else if (raw.answer === "true") {
+      answer = true;
+    } else if (raw.answer === "false") {
+      answer = false;
+    }
     return {
       kind: "trueFalse",
       ...base,
-      answer: typeof raw.answer === "boolean" ? raw.answer : raw.answer === "true"
+      answer
     };
   }
   if (kind === "fillInBlanks") {
@@ -195,7 +238,30 @@ function parseAssessmentDescriptor(raw) {
       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") {
+  if (kind === "sortParagraphs") {
+    return {
+      kind: "sortParagraphs",
+      ...base,
+      paragraphs: Array.isArray(raw.paragraphs) ? raw.paragraphs.filter((p) => typeof p === "string") : [],
+      correctOrder: Array.isArray(raw.correctOrder) ? raw.correctOrder.filter((n) => typeof n === "number" && Number.isFinite(n)) : []
+    };
+  }
+  if (kind === "guessTheAnswer") {
+    return {
+      kind: "guessTheAnswer",
+      ...base,
+      answer: typeof raw.answer === "string" ? raw.answer : ""
+    };
+  }
+  if (kind === "multimediaChoice") {
+    return {
+      kind: "multimediaChoice",
+      ...base,
+      choices: Array.isArray(raw.choices) ? raw.choices.filter((c) => typeof c === "string") : [],
+      answer: typeof raw.answer === "string" ? raw.answer : ""
+    };
+  }
+  if (typeof kind === "string" && kind !== "mcq" && kind !== "trueFalse" && kind !== "fillInBlanks" && kind !== "findHotspot" && kind !== "findMultipleHotspots" && kind !== "sortParagraphs" && kind !== "guessTheAnswer" && kind !== "multimediaChoice") {
     return {
       kind,
       ...base,
@@ -207,7 +273,15 @@ function parseAssessmentDescriptor(raw) {
     kind: kind === "mcq" ? "mcq" : void 0,
     ...base,
     choices: Array.isArray(raw.choices) ? raw.choices.filter((c) => typeof c === "string") : [],
-    answer: typeof raw.answer === "string" ? raw.answer : ""
+    answer: typeof raw.answer === "string" ? raw.answer : "",
+    answers: Array.isArray(raw.answers) ? raw.answers.filter((a) => typeof a === "string") : void 0,
+    shuffleChoices: typeof raw.shuffleChoices === "boolean" ? raw.shuffleChoices : void 0,
+    shuffleSeed: typeof raw.shuffleSeed === "string" || typeof raw.shuffleSeed === "number" ? raw.shuffleSeed : void 0,
+    choiceFeedback: raw.choiceFeedback && typeof raw.choiceFeedback === "object" && !Array.isArray(raw.choiceFeedback) ? Object.fromEntries(
+      Object.entries(raw.choiceFeedback).filter(
+        (entry) => typeof entry[1] === "string"
+      )
+    ) : void 0
   };
 }
 function parseCourseDescriptorInput(input) {
@@ -251,7 +325,7 @@ function parseCourseDescriptorInput(input) {
 }
 
 // src/descriptor/validateCourse.ts
-var import_core3 = require("@lessonkit/core");
+var import_core4 = require("@lessonkit/core");
 var import_themes2 = require("@lessonkit/themes");
 
 // src/spaPath.ts
@@ -282,43 +356,32 @@ function assertResolvedPathUnderRoot(root, target) {
     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)) {
+function resolvePhysicalPathForCheck(p) {
+  const resolved = resolveComparablePath(p);
+  try {
+    return import_node_fs.realpathSync.native(resolved);
+  } catch {
+    let probe = resolved;
+    let suffix = "";
+    while (true) {
       try {
-        current = (0, import_node_fs.realpathSync)(next);
+        const physical = import_node_fs.realpathSync.native(probe);
+        return suffix ? (0, import_node_path.join)(physical, suffix) : physical;
       } catch {
-        current = next;
+        if (probe === (0, import_node_path.dirname)(probe)) {
+          return resolved;
+        }
+        const segment = (0, import_node_path.basename)(probe);
+        suffix = suffix ? (0, import_node_path.join)(segment, suffix) : segment;
+        probe = (0, import_node_path.dirname)(probe);
       }
-    } 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);
-  }
+  const rootPhysical = resolvePhysicalPathForCheck(root);
+  const targetPhysical = resolvePhysicalPathForCheck(target);
+  assertResolvedPathUnderRoot(rootPhysical, targetPhysical);
 }
 function normalizePathForComparison(p) {
   const resolved = resolveComparablePath(p);
@@ -341,6 +404,113 @@ function isResolvedPathUnderRoot(root, target) {
   return !rel.startsWith("..") && !(0, import_node_path.isAbsolute)(rel);
 }
 
+// src/validateProjectPaths.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var RESERVED_OUTPUT_SEGMENTS = /* @__PURE__ */ new Set([".git", "node_modules", ".github"]);
+function isReservedOutputPath(value) {
+  let normalized = value.replace(/\\/g, "/");
+  while (normalized.startsWith("/")) normalized = normalized.slice(1);
+  while (normalized.endsWith("/")) normalized = normalized.slice(0, -1);
+  const segments = normalized.split("/").filter(Boolean);
+  return segments.some((segment) => RESERVED_OUTPUT_SEGMENTS.has(segment));
+}
+function validateManifestName(name) {
+  if (!name.length) {
+    return "must be a non-empty string";
+  }
+  if (name.includes("/") || name.includes("\\")) {
+    return "must not contain path separators";
+  }
+  if (!isSafeRelativeSpaPath(name)) {
+    return "must be a safe relative name without '..' segments or absolute prefixes";
+  }
+  if (isReservedOutputPath(name) || isReservedOutputPath(`${name}.lkcourse`)) {
+    return "must not target reserved directories (.git, node_modules, .github)";
+  }
+  return null;
+}
+function isReservedResolvedOutputPath(projectRoot, resolved) {
+  const rootResolved = resolveComparablePath(projectRoot);
+  const targetResolved = resolveComparablePath(resolved);
+  try {
+    const rootReal = (0, import_node_fs2.existsSync)(rootResolved) ? (0, import_node_fs2.realpathSync)(rootResolved) : rootResolved;
+    const targetReal = (0, import_node_fs2.existsSync)(targetResolved) ? (0, import_node_fs2.realpathSync)(targetResolved) : targetResolved;
+    const rel = relativePathUnderRoot(rootReal, targetReal);
+    return isReservedOutputPath(rel);
+  } catch {
+    return isReservedOutputPath(resolved);
+  }
+}
+function validatePathField(value, fieldPath, projectRoot, issues, options) {
+  if (!isSafeRelativeSpaPath(value)) {
+    issues.push({
+      path: fieldPath,
+      message: "path must be relative without '..' segments or absolute prefixes"
+    });
+    return;
+  }
+  if (options?.rejectReserved && isReservedOutputPath(value)) {
+    issues.push({
+      path: fieldPath,
+      message: "path must not target reserved directories (.git, node_modules, .github)"
+    });
+    return;
+  }
+  try {
+    assertRealPathUnderRoot(projectRoot, (0, import_node_path2.resolve)(projectRoot, value));
+  } catch {
+    issues.push({
+      path: fieldPath,
+      message: "path must resolve inside the project root"
+    });
+  }
+}
+function validateProjectPaths(projectRoot, paths) {
+  const issues = [];
+  const root = (0, import_node_path2.resolve)(projectRoot);
+  if (paths.spaDistDir?.trim()) {
+    validatePathField(paths.spaDistDir.trim(), "paths.spaDistDir", root, issues, {
+      rejectReserved: true
+    });
+  }
+  if (paths.lxpackOutDir?.trim()) {
+    validatePathField(paths.lxpackOutDir.trim(), "paths.lxpackOutDir", root, issues, {
+      rejectReserved: true
+    });
+  }
+  if (paths.outputBaseDir?.trim()) {
+    validatePathField(paths.outputBaseDir.trim(), "paths.outputBaseDir", root, issues, {
+      rejectReserved: true
+    });
+  }
+  return issues;
+}
+function resolveSafePackageOutputOverride(projectRoot, override) {
+  const root = (0, import_node_path2.resolve)(projectRoot);
+  const trimmed = override.trim();
+  if (!trimmed) {
+    throw new Error("output override must be a non-empty path");
+  }
+  if ((0, import_node_path2.isAbsolute)(trimmed)) {
+    const resolved2 = (0, import_node_path2.resolve)(trimmed);
+    assertRealPathUnderRoot(root, resolved2);
+    if (isReservedOutputPath(trimmed) || isReservedResolvedOutputPath(root, resolved2)) {
+      throw new Error(`unsafe output path: ${override} targets a reserved directory`);
+    }
+    return resolved2;
+  }
+  if (!isSafeRelativeSpaPath(trimmed)) {
+    throw new Error(`unsafe output path: ${override}`);
+  }
+  const resolved = (0, import_node_path2.resolve)(root, trimmed);
+  assertRealPathUnderRoot(root, resolved);
+  if (isReservedOutputPath(trimmed) || isReservedResolvedOutputPath(root, resolved)) {
+    throw new Error(`unsafe output path: ${override} targets a reserved directory`);
+  }
+  return resolved;
+}
+
 // src/theme.ts
 var import_themes = require("@lessonkit/themes");
 function themeToLxpackRuntime(input) {
@@ -358,6 +528,7 @@ function themeToLxpackRuntime(input) {
 
 // src/descriptor/validateAssessments.ts
 var import_core2 = require("@lessonkit/core");
+var import_core3 = 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" });
@@ -373,9 +544,44 @@ var validateMcqLike = (assessment, path, issues) => {
   }
   if (!assessment.answer.trim()) {
     issues.push({ path: `${path}.answer`, message: "answer is required" });
-  } else if (trimmedChoices.length && !trimmedChoices.includes(assessment.answer.trim())) {
+  } else if (!("answers" in assessment && (0, import_core3.isMultiSelectMcq)({ answers: assessment.answers })) && trimmedChoices.length && !trimmedChoices.includes(assessment.answer.trim())) {
     issues.push({ path: `${path}.answer`, message: "answer must match a choice" });
   }
+  if ("answers" in assessment && assessment.answers !== void 0) {
+    if (!Array.isArray(assessment.answers)) {
+      issues.push({ path: `${path}.answers`, message: "answers must be an array when provided" });
+    } else {
+      const trimmedAnswers = assessment.answers.map((a) => a.trim()).filter((a) => a.length > 0);
+      if (assessment.answers.length > 0 && trimmedAnswers.length === 0) {
+        issues.push({ path: `${path}.answers`, message: "answers must include non-empty strings" });
+      }
+      const uniqueAnswers = new Set(trimmedAnswers);
+      if (trimmedAnswers.length !== uniqueAnswers.size) {
+        issues.push({ path: `${path}.answers`, message: "answers must be unique" });
+      }
+      for (const ans of trimmedAnswers) {
+        if (trimmedChoices.length && !trimmedChoices.includes(ans)) {
+          issues.push({ path: `${path}.answers`, message: "each answer must match a choice" });
+          break;
+        }
+      }
+    }
+  }
+  if ("choiceFeedback" in assessment && assessment.choiceFeedback !== void 0) {
+    if (typeof assessment.choiceFeedback !== "object" || assessment.choiceFeedback === null) {
+      issues.push({ path: `${path}.choiceFeedback`, message: "choiceFeedback must be an object" });
+    } else {
+      for (const key of Object.keys(assessment.choiceFeedback)) {
+        if (!trimmedChoices.includes(key.trim())) {
+          issues.push({
+            path: `${path}.choiceFeedback`,
+            message: "choiceFeedback keys must match choice labels"
+          });
+          break;
+        }
+      }
+    }
+  }
   const uniqueChoices = new Set(trimmedChoices);
   if (trimmedChoices.length !== uniqueChoices.size) {
     issues.push({ path: `${path}.choices`, message: "choices must be unique" });
@@ -395,6 +601,12 @@ function maxAchievableAssessmentScore(assessment) {
   if (kind === "findMultipleHotspots" && assessment.kind === "findMultipleHotspots") {
     return assessment.correctTargetIds?.map((id) => id.trim()).filter((id) => id.length > 0).length ?? 0;
   }
+  if (kind === "sortParagraphs" && assessment.kind === "sortParagraphs") {
+    return assessment.paragraphs?.length ?? assessment.correctOrder?.length ?? 0;
+  }
+  if ("answers" in assessment && Array.isArray(assessment.answers) && assessment.answers.length > 1) {
+    return assessment.answers.filter((a) => a.trim().length > 0).length;
+  }
   return 1;
 }
 var ASSESSMENT_VALIDATORS = {
@@ -417,8 +629,30 @@ var ASSESSMENT_VALIDATORS = {
         message: "template must include at least one blank wrapped in asterisks for fillInBlanks"
       });
     }
-    const explicitBlanks = assessment.blanks?.map((b) => ({ id: b.id?.trim() ?? "", answer: b.answer?.trim() ?? "" })).filter((b) => b.id.length > 0 && b.answer.length > 0) ?? [];
-    if (assessment.blanks !== void 0 && explicitBlanks.length === 0) {
+    const explicitBlanks = [];
+    if (assessment.blanks !== void 0) {
+      for (let i = 0; i < assessment.blanks.length; i++) {
+        const blank = assessment.blanks[i];
+        if (!blank || typeof blank !== "object") {
+          issues.push({
+            path: `${path}.blanks[${i}]`,
+            message: "blank entry must be an object with non-empty id and answer"
+          });
+          continue;
+        }
+        const id = blank.id?.trim() ?? "";
+        const answer = blank.answer?.trim() ?? "";
+        if (!id || !answer) {
+          issues.push({
+            path: `${path}.blanks[${i}]`,
+            message: "blank entry must include non-empty id and answer"
+          });
+          continue;
+        }
+        explicitBlanks.push({ id, answer });
+      }
+    }
+    if (assessment.blanks !== void 0 && explicitBlanks.length === 0 && !issues.some((issue) => issue.path?.startsWith(`${path}.blanks`))) {
       issues.push({
         path: `${path}.blanks`,
         message: "blanks must include at least one entry with non-empty id and answer"
@@ -458,7 +692,31 @@ var ASSESSMENT_VALIDATORS = {
         message: "at least one non-empty correctTargetId is required for findMultipleHotspots"
       });
     }
-  }
+  },
+  sortParagraphs: (assessment, path, issues) => {
+    if (assessment.kind !== "sortParagraphs") return;
+    if (!Array.isArray(assessment.paragraphs) || assessment.paragraphs.length === 0) {
+      issues.push({ path: `${path}.paragraphs`, message: "paragraphs is required for sortParagraphs" });
+      return;
+    }
+    if (!Array.isArray(assessment.correctOrder) || assessment.correctOrder.length === 0) {
+      issues.push({ path: `${path}.correctOrder`, message: "correctOrder is required for sortParagraphs" });
+      return;
+    }
+    if (assessment.correctOrder.length !== assessment.paragraphs.length) {
+      issues.push({
+        path: `${path}.correctOrder`,
+        message: "correctOrder length must match paragraphs length for sortParagraphs"
+      });
+    }
+  },
+  guessTheAnswer: (assessment, path, issues) => {
+    if (assessment.kind !== "guessTheAnswer") return;
+    if (!assessment.answer?.trim()) {
+      issues.push({ path: `${path}.answer`, message: "answer is required for guessTheAnswer" });
+    }
+  },
+  multimediaChoice: validateMcqLike
 };
 function validateAssessmentEntry(assessment, index, issues, checkIds) {
   const path = `assessments[${index}]`;
@@ -513,7 +771,7 @@ 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_core3.validateId)(input.courseId, "courseId");
+  const course = (0, import_core4.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" });
@@ -566,6 +824,20 @@ function validateCourseDescriptor(input) {
       });
     }
   }
+  const descriptorSpaDistDir = input.spaDistDir?.trim();
+  if (descriptorSpaDistDir) {
+    if (!isSafeRelativeSpaPath(descriptorSpaDistDir)) {
+      issues.push({
+        path: "spaDistDir",
+        message: "spaDistDir must be a relative path without '..' segments or absolute prefixes"
+      });
+    } else if (isReservedOutputPath(descriptorSpaDistDir)) {
+      issues.push({
+        path: "spaDistDir",
+        message: "spaDistDir must not target reserved directories (.git, node_modules, .github)"
+      });
+    }
+  }
   if (layout === "single-spa" && (input.lessons?.length ?? 0) > 1) {
     issues.push({
       path: "lessons",
@@ -576,7 +848,7 @@ function validateCourseDescriptor(input) {
   const spaPaths = /* @__PURE__ */ new Set();
   for (const [index, lesson] of (input.lessons ?? []).entries()) {
     const path = `lessons[${index}]`;
-    const lessonResult = (0, import_core3.validateId)(lesson.id, `${path}.id`);
+    const lessonResult = (0, import_core4.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)) {
@@ -608,7 +880,7 @@ function validateCourseDescriptor(input) {
   }
   if (layout === "single-spa" && input.spaLessonId?.trim()) {
     const spaId = input.spaLessonId.trim();
-    const spaResult = (0, import_core3.validateId)(spaId, "spaLessonId");
+    const spaResult = (0, import_core4.validateId)(spaId, "spaLessonId");
     if (!spaResult.ok) {
       issues.push(...spaResult.issues.map((i) => ({ path: i.path, message: i.message })));
     } else if (!lessonIds.has(spaResult.id)) {
@@ -626,6 +898,8 @@ function validateCourseDescriptor(input) {
 }
 
 // src/assessments.ts
+var import_core5 = require("@lessonkit/core");
+var DEFAULT_SHELL_PASSING_SCORE = 1;
 function escapeShellText(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
@@ -634,7 +908,7 @@ function decodeShellEntities(text) {
 }
 function containsUnsafeShellMarkup(text) {
   const decoded = decodeShellEntities(text);
-  return /<\/script/i.test(decoded) || /<!--/.test(decoded) || /</.test(decoded);
+  return /<\/script/i.test(decoded) || /<!--/.test(decoded) || /<[a-zA-Z!/]/.test(decoded);
 }
 function sanitizeShellField(text) {
   if (containsUnsafeShellMarkup(text)) return null;
@@ -649,6 +923,8 @@ function mcqToLxpack(assessment) {
   const checkId = sanitizeShellField(assessment.checkId);
   const prompt = sanitizeShellField(assessment.question);
   if (!checkId || !prompt) return null;
+  const normalizedAnswer = assessment.answer.trim();
+  const multiCorrect = assessment.answers && assessment.answers.length > 1 ? new Set(assessment.answers.map((a) => a.trim())) : /* @__PURE__ */ new Set([normalizedAnswer]);
   const choices = assessment.choices.map((text, index) => {
     const sanitizedText = sanitizeShellField(text);
     if (!sanitizedText) return null;
@@ -656,17 +932,21 @@ function mcqToLxpack(assessment) {
     return {
       id,
       text: sanitizedText,
-      correct: text === assessment.answer
+      correct: multiCorrect.has(text.trim())
     };
   });
   if (choices.some((choice) => choice === null)) return null;
+  const multiSelect = (0, import_core5.isMultiSelectMcq)(assessment);
   return {
     id: checkId,
-    passingScore: assessment.passingScore ?? 1,
+    passingScore: assessment.passingScore ?? DEFAULT_SHELL_PASSING_SCORE,
+    shuffleChoices: assessment.shuffleChoices === true ? true : void 0,
+    showFeedback: assessment.choiceFeedback && Object.keys(assessment.choiceFeedback).length > 0 ? "immediate" : void 0,
     questions: [
       {
         id: "q1",
         prompt,
+        ...multiSelect ? { selectionMode: "multiple" } : {},
         choices
       }
     ]
@@ -695,7 +975,20 @@ function assessmentDescriptorToLxpack(assessment) {
   if (kind === "findMultipleHotspots") {
     return null;
   }
-  if ("choices" in assessment && "answer" in assessment && typeof assessment.answer === "string") {
+  if (kind === "sortParagraphs" || kind === "guessTheAnswer") {
+    return null;
+  }
+  if (kind === "multimediaChoice" && assessment.kind === "multimediaChoice") {
+    return mcqToLxpack({
+      kind: "mcq",
+      checkId: assessment.checkId,
+      question: assessment.question,
+      choices: assessment.choices,
+      answer: assessment.answer,
+      passingScore: assessment.passingScore
+    });
+  }
+  if ((kind === "mcq" || assessment.kind === void 0) && "choices" in assessment && "answer" in assessment && typeof assessment.answer === "string") {
     return mcqToLxpack(assessment);
   }
   return null;
@@ -707,11 +1000,20 @@ function extractAssessments(descriptor) {
 // src/descriptor/validateInjectableAssessments.ts
 function validateInjectableAssessments(descriptor) {
   const issues = [];
+  const spaOnlyKinds = /* @__PURE__ */ new Set([
+    "fillInBlanks",
+    "findHotspot",
+    "findMultipleHotspots",
+    "sortParagraphs",
+    "guessTheAnswer"
+  ]);
   (descriptor.assessments ?? []).forEach((assessment, index) => {
     if (assessmentDescriptorToLxpack(assessment) === null) {
+      const kind = assessment.kind ?? "mcq";
+      const hint = spaOnlyKinds.has(kind) ? " \u2014 score in the SPA only; remove from lessonkit.json for LMS targets or use an injectable kind (mcq, trueFalse)" : "";
       issues.push({
         path: `assessments[${index}]`,
-        message: `assessment kind "${assessment.kind ?? "mcq"}" (checkId "${assessment.checkId}") is not injected into LMS shell quizzes`
+        message: `assessment kind "${kind}" (checkId "${assessment.checkId}") is not injected into LMS shell quizzes${hint}`
       });
     }
   });
@@ -727,7 +1029,7 @@ var LMS_SHELL_TARGETS = /* @__PURE__ */ new Set([
   "cmi5"
 ]);
 function appendActivityIriIssues(issues, descriptor, target) {
-  const hasXapiTracking = Boolean(descriptor.tracking?.xapi);
+  const hasXapiTracking = Boolean(descriptor.tracking?.xapi?.activityIri?.trim());
   const requiresForTarget = target === "xapi" || target === "cmi5";
   if (!hasXapiTracking && !requiresForTarget) return;
   const activityIri = descriptor.tracking?.xapi?.activityIri?.trim();
@@ -782,26 +1084,26 @@ function validateDescriptorForTarget(input, target) {
 }
 
 // src/validateReactParity.ts
-var import_node_fs2 = require("fs");
-var import_node_path2 = require("path");
+var import_node_fs3 = require("fs");
+var import_node_path3 = require("path");
 var SCANNABLE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
 function collectSourceUnderSrc(projectRoot, issues) {
-  const srcDir = (0, import_node_path2.join)(projectRoot, "src");
-  if (!(0, import_node_fs2.existsSync)(srcDir)) return [];
+  const srcDir = (0, import_node_path3.join)(projectRoot, "src");
+  if (!(0, import_node_fs3.existsSync)(srcDir)) return [];
   const results = [];
   const walk = (dir) => {
-    for (const entry of (0, import_node_fs2.readdirSync)(dir)) {
-      const abs = (0, import_node_path2.join)(dir, entry);
+    for (const entry of (0, import_node_fs3.readdirSync)(dir)) {
+      const abs = (0, import_node_path3.join)(dir, entry);
       let stat2;
       try {
-        stat2 = (0, import_node_fs2.lstatSync)(abs);
+        stat2 = (0, import_node_fs3.lstatSync)(abs);
       } catch {
         continue;
       }
       if (stat2.isSymbolicLink()) {
         issues.push({
-          path: (0, import_node_path2.relative)(projectRoot, abs),
-          message: `Source tree contains symlink (rejected for parity scan): ${(0, import_node_path2.relative)(projectRoot, abs)}`,
+          path: (0, import_node_path3.relative)(projectRoot, abs),
+          message: `Source tree contains symlink (rejected for parity scan): ${(0, import_node_path3.relative)(projectRoot, abs)}`,
           severity: "error"
         });
         continue;
@@ -811,8 +1113,8 @@ function collectSourceUnderSrc(projectRoot, issues) {
           assertRealPathUnderRoot(projectRoot, abs);
         } catch {
           issues.push({
-            path: (0, import_node_path2.relative)(projectRoot, abs),
-            message: `Source directory escapes project root: ${(0, import_node_path2.relative)(projectRoot, abs)}`,
+            path: (0, import_node_path3.relative)(projectRoot, abs),
+            message: `Source directory escapes project root: ${(0, import_node_path3.relative)(projectRoot, abs)}`,
             severity: "error"
           });
           continue;
@@ -823,13 +1125,13 @@ function collectSourceUnderSrc(projectRoot, issues) {
           assertRealPathUnderRoot(projectRoot, abs);
         } catch {
           issues.push({
-            path: (0, import_node_path2.relative)(projectRoot, abs),
-            message: `Source file escapes project root: ${(0, import_node_path2.relative)(projectRoot, abs)}`,
+            path: (0, import_node_path3.relative)(projectRoot, abs),
+            message: `Source file escapes project root: ${(0, import_node_path3.relative)(projectRoot, abs)}`,
             severity: "error"
           });
           continue;
         }
-        results.push((0, import_node_path2.relative)(projectRoot, abs));
+        results.push((0, import_node_path3.relative)(projectRoot, abs));
       }
     }
   };
@@ -848,10 +1150,10 @@ function readAppSources(projectRoot, appSources, issues, customSourcesProvided)
       }
       return null;
     }
-    const abs = (0, import_node_path2.join)(projectRoot, rel);
+    const abs = (0, import_node_path3.join)(projectRoot, rel);
     try {
       assertRealPathUnderRoot(projectRoot, abs);
-      if ((0, import_node_fs2.existsSync)(abs) && (0, import_node_fs2.lstatSync)(abs).isSymbolicLink()) {
+      if ((0, import_node_fs3.existsSync)(abs) && (0, import_node_fs3.lstatSync)(abs).isSymbolicLink()) {
         issues.push({
           path: rel,
           message: `appSources path is a symlink: ${rel}`,
@@ -867,8 +1169,8 @@ function readAppSources(projectRoot, appSources, issues, customSourcesProvided)
       });
       return null;
     }
-    if (!(0, import_node_fs2.existsSync)(abs)) return null;
-    return (0, import_node_fs2.readFileSync)(abs, "utf8");
+    if (!(0, import_node_fs3.existsSync)(abs)) return null;
+    return (0, import_node_fs3.readFileSync)(abs, "utf8");
   }).filter((content) => content != null).join("\n");
 }
 function stripComments(source) {
@@ -943,9 +1245,20 @@ function courseConfigCourseIdPresent(source, courseId) {
   if (literalPattern.test(stripped)) return true;
   return idUsedViaConstant(source, "courseId", courseId, extractStringConstants(source));
 }
+function courseMetaCourseIdPresent(source, courseId) {
+  const constants = extractStringConstants(source);
+  const stripped = stripComments(source);
+  for (const [name, value] of constants) {
+    if (value !== courseId) continue;
+    if (!new RegExp(`\\bcourseId\\s*:\\s*${name}\\b`).test(stripped)) continue;
+    if (/\blessons\s*:\s*\S/.test(stripped)) return true;
+  }
+  return false;
+}
 function courseIdPresent(source, courseId) {
   if (idPropPresent(source, "courseId", courseId)) return true;
   if (idUsedViaConstant(source, "courseId", courseId, extractStringConstants(source))) return true;
+  if (courseMetaCourseIdPresent(source, courseId)) return true;
   return courseConfigCourseIdPresent(source, courseId);
 }
 function checkIdPresent(source, checkId) {
@@ -1014,88 +1327,13 @@ function validateReactManifestParity(opts) {
   return issues;
 }
 
-// src/validateProjectPaths.ts
-var import_node_path3 = require("path");
-var RESERVED_OUTPUT_SEGMENTS = /* @__PURE__ */ new Set([".git", "node_modules", ".github"]);
-function isReservedOutputPath(value) {
-  const normalized = value.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
-  const segments = normalized.split("/").filter(Boolean);
-  return segments.some((segment) => RESERVED_OUTPUT_SEGMENTS.has(segment));
-}
-function validatePathField(value, fieldPath, projectRoot, issues, options) {
-  if (!isSafeRelativeSpaPath(value)) {
-    issues.push({
-      path: fieldPath,
-      message: "path must be relative without '..' segments or absolute prefixes"
-    });
-    return;
-  }
-  if (options?.rejectReserved && isReservedOutputPath(value)) {
-    issues.push({
-      path: fieldPath,
-      message: "path must not target reserved directories (.git, node_modules, .github)"
-    });
-    return;
-  }
-  try {
-    assertRealPathUnderRoot(projectRoot, (0, import_node_path3.resolve)(projectRoot, value));
-  } catch {
-    issues.push({
-      path: fieldPath,
-      message: "path must resolve inside the project root"
-    });
-  }
-}
-function validateProjectPaths(projectRoot, paths) {
-  const issues = [];
-  const root = (0, import_node_path3.resolve)(projectRoot);
-  if (paths.spaDistDir?.trim()) {
-    validatePathField(paths.spaDistDir.trim(), "paths.spaDistDir", root, issues);
-  }
-  if (paths.lxpackOutDir?.trim()) {
-    validatePathField(paths.lxpackOutDir.trim(), "paths.lxpackOutDir", root, issues, {
-      rejectReserved: true
-    });
-  }
-  if (paths.outputBaseDir?.trim()) {
-    validatePathField(paths.outputBaseDir.trim(), "paths.outputBaseDir", root, issues, {
-      rejectReserved: true
-    });
-  }
-  return issues;
-}
-function resolveSafePackageOutputOverride(projectRoot, override) {
-  const root = (0, import_node_path3.resolve)(projectRoot);
-  const trimmed = override.trim();
-  if (!trimmed) {
-    throw new Error("output override must be a non-empty path");
-  }
-  if ((0, import_node_path3.isAbsolute)(trimmed)) {
-    const resolved2 = (0, import_node_path3.resolve)(trimmed);
-    assertRealPathUnderRoot(root, resolved2);
-    if (isReservedOutputPath(trimmed)) {
-      throw new Error(`unsafe output path: ${override} targets a reserved directory`);
-    }
-    return resolved2;
-  }
-  if (!isSafeRelativeSpaPath(trimmed)) {
-    throw new Error(`unsafe output path: ${override}`);
-  }
-  if (isReservedOutputPath(trimmed)) {
-    throw new Error(`unsafe output path: ${override} targets a reserved directory`);
-  }
-  const resolved = (0, import_node_path3.resolve)(root, trimmed);
-  assertRealPathUnderRoot(root, resolved);
-  return resolved;
-}
-
 // src/mapIds.ts
-var import_core4 = require("@lessonkit/core");
+var import_core6 = require("@lessonkit/core");
 function mapLessonkitIds(descriptor) {
-  const courseId = (0, import_core4.assertValidId)(descriptor.courseId, "courseId");
-  const lessonIds = descriptor.lessons.map((l) => (0, import_core4.assertValidId)(l.id, "lessonId"));
+  const courseId = (0, import_core6.assertValidId)(descriptor.courseId, "courseId");
+  const lessonIds = descriptor.lessons.map((l) => (0, import_core6.assertValidId)(l.id, "lessonId"));
   const checkIds = (descriptor.assessments ?? []).map(
-    (a) => (0, import_core4.assertValidId)(a.checkId, "checkId")
+    (a) => (0, import_core6.assertValidId)(a.checkId, "checkId")
   );
   return { courseId, lessonIds, checkIds };
 }
@@ -1220,7 +1458,7 @@ async function resolveSpaDirs(options) {
 
 // src/spaDistValidation.ts
 var import_promises2 = require("fs/promises");
-var import_node_fs3 = require("fs");
+var import_node_fs4 = require("fs");
 var import_node_path5 = require("path");
 async function assertSpaDistContentsSafe(spaDirs, projectRoot) {
   for (const [label, dir] of Object.entries(spaDirs)) {
@@ -1231,7 +1469,7 @@ async function assertSpaDistContentsSafe(spaDirs, projectRoot) {
     }
     let rootReal;
     try {
-      rootReal = (0, import_node_fs3.realpathSync)(dirResolved);
+      rootReal = (0, import_node_fs4.realpathSync)(dirResolved);
     } catch {
       throw new Error(`spa dist for "${label}" is not readable: ${dir}`);
     }
@@ -1260,7 +1498,7 @@ async function walkDistDir(rootReal, current, label) {
     }
     let entryReal;
     try {
-      entryReal = (0, import_node_fs3.realpathSync)(entryPath);
+      entryReal = (0, import_node_fs4.realpathSync)(entryPath);
     } catch (err) {
       throw new Error(
         `spa dist for "${label}" could not resolve path: ${entryPath}`,
@@ -1285,8 +1523,10 @@ async function writeLxpackProject(options) {
   const descriptor = validation.descriptor;
   const injectableIssues = validateInjectableAssessments(descriptor);
   if (injectableIssues.length > 0) {
-    throw new Error(injectableIssues.map((i) => `${i.path}: ${i.message}`).join("; "));
-  }
+    throw new Error(
+      injectableIssues.map((i) => `${i.path ?? "assessments"}: ${i.message}`).join("; ")
+    );
+  }
   const outDir = (0, import_node_path6.resolve)(options.outDir);
   assertRealPathUnderRoot((0, import_node_path6.resolve)(options.projectRoot), outDir);
   const spaDirs = await resolveSpaDirs({ ...options, descriptor });
@@ -1312,8 +1552,8 @@ async function writeLxpackProject(options) {
 }
 
 // src/packageCourse.ts
-var import_node_path10 = require("path");
-var fsp3 = __toESM(require("fs/promises"), 1);
+var import_node_path11 = require("path");
+var fsp4 = __toESM(require("fs/promises"), 1);
 var import_api2 = require("@lxpack/api");
 
 // src/packaging/validateInputs.ts
@@ -1348,6 +1588,19 @@ function validatePackageInputs(options) {
       ]
     };
   }
+  if (isReservedOutputPath(outDir) || isReservedResolvedOutputPath(projectRoot, outDir)) {
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      issues: [
+        {
+          path: "outDir",
+          message: "outDir must not target reserved directories (.git, node_modules, .github)"
+        }
+      ]
+    };
+  }
   if (outputBaseDir && !isSafeRelativeSpaPath(outputBaseDir)) {
     return {
       ok: false,
@@ -1405,6 +1658,19 @@ function validatePackageInputs(options) {
         ]
       };
     }
+    if (isReservedOutputPath(outputBaseDir) || isReservedResolvedOutputPath(projectRoot, resolvedOutputBase)) {
+      return {
+        ok: false,
+        courseDir: outDir,
+        target,
+        issues: [
+          {
+            path: "outputBaseDir",
+            message: "outputBaseDir must not target reserved directories (.git, node_modules, .github)"
+          }
+        ]
+      };
+    }
   }
   if (output) {
     const resolvedOutput = (0, import_node_path7.isAbsolute)(output) ? (0, import_node_path7.resolve)(output) : (0, import_node_path7.resolve)(projectRoot, output);
@@ -1426,6 +1692,20 @@ function validatePackageInputs(options) {
         ]
       };
     }
+    const outputRel = (0, import_node_path7.isAbsolute)(output) ? output : output;
+    if (isReservedOutputPath(outputRel) || isReservedResolvedOutputPath(projectRoot, resolvedOutput)) {
+      return {
+        ok: false,
+        courseDir: outDir,
+        target,
+        issues: [
+          {
+            path: "output",
+            message: "output must not target reserved directories (.git, node_modules, .github)"
+          }
+        ]
+      };
+    }
   }
   return { ok: true, outDir, projectRoot };
 }
@@ -1518,11 +1798,14 @@ async function isStalePromoteLock(lockPath) {
     return true;
   }
 }
+var PROMOTE_LOCK_TIMEOUT_MS = 15e3;
 async function withPromoteLock(outDir, fn) {
   const lockPath = promoteLockPath(outDir);
   await fsp.mkdir((0, import_node_path8.dirname)(outDir), { recursive: true });
   let lockHandle;
-  for (let attempt = 0; attempt < 200; attempt++) {
+  const maxAttempts = 400;
+  const started = Date.now();
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
     try {
       lockHandle = await fsp.open(lockPath, "wx");
       await lockHandle.writeFile(`${process.pid}
@@ -1540,7 +1823,9 @@ ${Date.now()}
         );
         continue;
       }
-      await new Promise((resolveWait) => setTimeout(resolveWait, 25));
+      if (Date.now() - started >= PROMOTE_LOCK_TIMEOUT_MS) break;
+      const delayMs = Math.min(25 * 2 ** Math.floor(attempt / 20), 250);
+      await new Promise((resolveWait) => setTimeout(resolveWait, delayMs));
     }
   }
   if (!lockHandle) {
@@ -1709,14 +1994,29 @@ async function promoteStagingToOutDir(stagingDir, outDir, options) {
   });
 }
 
-// src/packaging/staging.ts
+// src/packaging/relocateOutput.ts
 var fsp2 = __toESM(require("fs/promises"), 1);
 var import_node_path9 = require("path");
+async function relocatePackageOutput(builtOutputPath, requestedOutputPath, projectRoot) {
+  if (!builtOutputPath || !requestedOutputPath) return builtOutputPath;
+  const resolvedBuilt = resolveComparablePath(builtOutputPath);
+  const resolvedRequested = resolveComparablePath(requestedOutputPath);
+  if (resolvedBuilt === resolvedRequested) return builtOutputPath;
+  const root = (0, import_node_path9.resolve)(projectRoot);
+  assertRealPathUnderRoot(root, resolvedRequested);
+  await fsp2.mkdir((0, import_node_path9.dirname)(resolvedRequested), { recursive: true });
+  await renameOrCopy(resolvedBuilt, resolvedRequested);
+  return resolvedRequested;
+}
+
+// src/packaging/staging.ts
+var fsp3 = __toESM(require("fs/promises"), 1);
+var import_node_path10 = require("path");
 var import_node_os = require("os");
 var import_api = require("@lxpack/api");
 async function buildStagingPackage(options) {
   const { target, output, dir, outputBaseDir, descriptor, ...writeOpts } = options;
-  const stagingDir = await fsp2.mkdtemp((0, import_node_path9.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
+  const stagingDir = await fsp3.mkdtemp((0, import_node_path10.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
   let succeeded = false;
   try {
     let spaDirs;
@@ -1748,14 +2048,28 @@ async function buildStagingPackage(options) {
     }
     const interchange = descriptorToInterchange(descriptor);
     const outputBase = outputBaseDir ?? ".lxpack/out";
-    await fsp2.mkdir((0, import_node_path9.join)(stagingDir, outputBase), { recursive: true });
-    const defaultOutput = output ?? (dir ? (0, import_node_path9.join)(outputBase, target) : (0, import_node_path9.join)(outputBase, `course-${target}.zip`));
+    await fsp3.mkdir((0, import_node_path10.join)(stagingDir, outputBase), { recursive: true });
+    const defaultOutput = dir ? (0, import_node_path10.join)(outputBase, target) : (0, import_node_path10.join)(outputBase, `course-${target}.zip`);
+    let packageOutput = output ?? defaultOutput;
+    let requestedOutputPath;
+    let requestedOutputDir;
+    if (output) {
+      const projectRoot = (0, import_node_path10.resolve)(writeOpts.projectRoot);
+      const requested = (0, import_node_path10.isAbsolute)(output) ? (0, import_node_path10.resolve)(output) : (0, import_node_path10.resolve)(projectRoot, output);
+      if (dir) {
+        requestedOutputDir = requested;
+        packageOutput = defaultOutput;
+      } else {
+        requestedOutputPath = requested;
+        packageOutput = defaultOutput;
+      }
+    }
     const build = await (0, import_api.packageLessonkit)({
       interchange,
       spaDirs,
       target,
       courseDir: stagingDir,
-      output: defaultOutput,
+      output: packageOutput,
       dir,
       outputBaseDir,
       outputAnchorDir: stagingDir,
@@ -1779,17 +2093,19 @@ async function buildStagingPackage(options) {
       stagingDir,
       build,
       outputPath: "outputPath" in build ? build.outputPath : void 0,
-      outputDir: "outputDir" in build ? build.outputDir : void 0
+      outputDir: "outputDir" in build ? build.outputDir : void 0,
+      requestedOutputPath,
+      requestedOutputDir
     };
   } catch (err) {
-    await fsp2.rm(stagingDir, { recursive: true, force: true }).catch(
+    await fsp3.rm(stagingDir, { recursive: true, force: true }).catch(
       /* v8 ignore next */
       () => void 0
     );
     throw err;
   } finally {
     if (!succeeded) {
-      await fsp2.rm(stagingDir, { recursive: true, force: true }).catch(
+      await fsp3.rm(stagingDir, { recursive: true, force: true }).catch(
         /* v8 ignore next */
         () => void 0
       );
@@ -1797,7 +2113,7 @@ async function buildStagingPackage(options) {
   }
 }
 async function ensureOutDirParent(outDir) {
-  await fsp2.mkdir((0, import_node_path9.dirname)(outDir), { recursive: true });
+  await fsp3.mkdir((0, import_node_path10.dirname)(outDir), { recursive: true });
 }
 
 // src/packaging/issueSeverity.ts
@@ -1808,17 +2124,23 @@ function isPackagingErrorIssue(issue) {
 function findPackagingErrorIssues(issues) {
   return (issues ?? []).filter(isPackagingErrorIssue);
 }
+function isPackagingWarningIssue(issue) {
+  return issue.severity?.toLowerCase() === "warning";
+}
+function findPackagingWarningIssues(issues) {
+  return (issues ?? []).filter(isPackagingWarningIssue);
+}
 
 // src/packageCourse.ts
 async function validateLessonkitProject(options) {
   return (0, import_api2.validateCourse)({
-    courseDir: (0, import_node_path10.resolve)(options.courseDir),
+    courseDir: (0, import_node_path11.resolve)(options.courseDir),
     target: options.target
   });
 }
 async function buildLessonkitProject(options) {
   const buildOptions = {
-    courseDir: (0, import_node_path10.resolve)(options.courseDir),
+    courseDir: (0, import_node_path11.resolve)(options.courseDir),
     target: options.target,
     output: options.output,
     dir: options.dir,
@@ -1849,7 +2171,7 @@ async function packageLessonkitCourse(options) {
   if (!descriptorValidation.ok) {
     return {
       ok: false,
-      courseDir: (0, import_node_path10.resolve)(writeOpts.outDir),
+      courseDir: (0, import_node_path11.resolve)(writeOpts.outDir),
       target,
       issues: descriptorValidation.issues.map((i) => ({
         path: i.path,
@@ -1875,16 +2197,31 @@ async function packageLessonkitCourse(options) {
       }))
     };
   }
-  const staged = await buildStagingPackage({
-    ...writeOpts,
-    descriptor,
-    target,
-    output,
-    dir,
-    outputBaseDir
-  });
+  let staged;
+  try {
+    staged = await buildStagingPackage({
+      ...writeOpts,
+      descriptor,
+      target,
+      output,
+      dir,
+      outputBaseDir
+    });
+  } catch (err) {
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      issues: [
+        {
+          path: "staging",
+          message: err instanceof Error ? err.message : String(err)
+        }
+      ]
+    };
+  }
   if (!staged.ok) {
-    await fsp3.rm(staged.stagingDir, { recursive: true, force: true }).catch(
+    await fsp4.rm(staged.stagingDir, { recursive: true, force: true }).catch(
       /* v8 ignore next */
       () => void 0
     );
@@ -1901,7 +2238,7 @@ 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(
+    await fsp4.rm(stagingDir, { recursive: true, force: true }).catch(
       /* v8 ignore next */
       () => void 0
     );
@@ -1918,13 +2255,13 @@ async function packageLessonkitCourse(options) {
       }))
     };
   }
-  const stagingRoot = await fsp3.realpath(stagingDir);
+  const stagingRoot = await fsp4.realpath(stagingDir);
   const artifactIssues = [
     validateArtifactInStaging(stagingRoot, staged.outputPath, "outputPath"),
     validateArtifactInStaging(stagingRoot, staged.outputDir, "outputDir")
   ].filter((issue) => issue != null);
   if (artifactIssues.length > 0) {
-    await fsp3.rm(stagingDir, { recursive: true, force: true }).catch(
+    await fsp4.rm(stagingDir, { recursive: true, force: true }).catch(
       /* v8 ignore next */
       () => void 0
     );
@@ -1937,8 +2274,27 @@ async function packageLessonkitCourse(options) {
       issues: artifactIssues
     };
   }
-  const remappedOutputPath = remapArtifactPaths(stagingRoot, outDir, staged.outputPath);
-  const remappedOutputDir = remapArtifactPaths(stagingRoot, outDir, staged.outputDir);
+  const buildWarningIssues = findPackagingWarningIssues(build.issues);
+  if (options.strictBuild && buildWarningIssues.length > 0) {
+    await fsp4.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: buildWarningIssues.map((i) => ({
+        path: i.path ?? "build",
+        message: i.message ?? "build warning",
+        severity: i.severity
+      }))
+    };
+  }
+  let remappedOutputPath = remapArtifactPaths(stagingRoot, outDir, staged.outputPath);
+  let remappedOutputDir = remapArtifactPaths(stagingRoot, outDir, staged.outputDir);
   const validation = {
     ok: true,
     manifest: build.manifest,
@@ -1951,7 +2307,7 @@ async function packageLessonkitCourse(options) {
       projectRoot: writeOpts.projectRoot
     });
   } catch (err) {
-    await fsp3.rm(stagingDir, { recursive: true, force: true }).catch(
+    await fsp4.rm(stagingDir, { recursive: true, force: true }).catch(
       /* v8 ignore next */
       () => void 0
     );
@@ -1969,6 +2325,32 @@ async function packageLessonkitCourse(options) {
       ]
     };
   }
+  try {
+    remappedOutputPath = await relocatePackageOutput(
+      remappedOutputPath,
+      staged.requestedOutputPath,
+      writeOpts.projectRoot
+    );
+    remappedOutputDir = await relocatePackageOutput(
+      remappedOutputDir,
+      staged.requestedOutputDir,
+      writeOpts.projectRoot
+    );
+  } catch (err) {
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      validation,
+      build,
+      issues: [
+        {
+          path: "output",
+          message: err instanceof Error ? err.message : String(err)
+        }
+      ]
+    };
+  }
   const remappedBuild = { ...build };
   if ("outputPath" in remappedBuild && remappedOutputPath !== void 0) {
     remappedBuild.outputPath = remappedOutputPath;
@@ -2012,8 +2394,9 @@ function parseLessonkitManifest(raw, label = "lessonkit.json", projectRoot) {
   }
   const nameRaw = config.name;
   const name = typeof nameRaw === "string" ? nameRaw.trim() : "";
-  if (!name) {
-    issues.push({ path: "name", message: "must be a non-empty string" });
+  const nameIssue = validateManifestName(name);
+  if (nameIssue) {
+    issues.push({ path: "name", message: nameIssue });
   }
   const courseRaw = config.course;
   if (Array.isArray(courseRaw)) {
@@ -2079,7 +2462,7 @@ function parseLessonkitManifest(raw, label = "lessonkit.json", projectRoot) {
         path: `paths.${key}`,
         message: "path must be relative without '..' segments or absolute prefixes"
       });
-    } else if ((key === "lxpackOutDir" || key === "outputBaseDir") && isReservedOutputPath(value)) {
+    } else if (isReservedOutputPath(value)) {
       issues.push({
         path: `paths.${key}`,
         message: "path must not target reserved directories (.git, node_modules, .github)"
@@ -2173,17 +2556,922 @@ function telemetryEventToLessonkit(event) {
 }
 
 // src/index.ts
+var import_validators4 = require("@lxpack/validators");
+
+// src/lkcourse/zip.ts
+var import_node_fs5 = require("fs");
+var import_node_path12 = require("path");
+var import_fflate = require("fflate");
+var MAX_LKCOURSE_UNCOMPRESSED_BYTES = 256 * 1024 * 1024;
+function canonicalZipEntryPath(entryPath) {
+  const slashNormalized = entryPath.replace(/\\/g, "/");
+  const canonical = (0, import_node_path12.normalize)(slashNormalized).replace(/\\/g, "/");
+  if (canonical !== slashNormalized) return null;
+  return canonical;
+}
+function isSafeZipEntryPath(entryPath) {
+  const canonical = canonicalZipEntryPath(entryPath);
+  if (!canonical?.length || canonical.startsWith("/") || canonical.includes("\0")) {
+    return false;
+  }
+  const segments = canonical.split("/").filter((s) => s.length > 0);
+  if (segments.some((s) => s === "..")) return false;
+  return segments.length > 0;
+}
+function createZip(entries) {
+  const zipped = {};
+  for (const [path, data] of entries) {
+    if (!isSafeZipEntryPath(path)) {
+      throw new Error(`unsafe zip entry path: ${path}`);
+    }
+    zipped[path.replace(/\\/g, "/")] = data instanceof Uint8Array ? data : new Uint8Array(data);
+  }
+  return (0, import_fflate.zipSync)(zipped, { level: 6 });
+}
+function readZip(archivePath) {
+  const issues = [];
+  let raw;
+  try {
+    raw = (0, import_node_fs5.readFileSync)(archivePath);
+  } catch {
+    return { ok: false, issues: [{ path: archivePath, message: "failed to read archive" }] };
+  }
+  if (!raw.length) {
+    return { ok: false, issues: [{ path: archivePath, message: "archive is empty" }] };
+  }
+  let unzipped;
+  try {
+    unzipped = (0, import_fflate.unzipSync)(raw);
+  } catch {
+    return { ok: false, issues: [{ path: archivePath, message: "invalid zip archive" }] };
+  }
+  const entries = /* @__PURE__ */ new Map();
+  let totalUncompressed = 0;
+  for (const [path, data] of Object.entries(unzipped)) {
+    const canonical = canonicalZipEntryPath(path);
+    if (!canonical || !isSafeZipEntryPath(canonical)) {
+      issues.push({ path, message: "unsafe zip entry path" });
+      continue;
+    }
+    if (entries.has(canonical)) {
+      issues.push({ path: canonical, message: "duplicate zip entry path" });
+      continue;
+    }
+    totalUncompressed += data.byteLength;
+    if (totalUncompressed > MAX_LKCOURSE_UNCOMPRESSED_BYTES) {
+      return {
+        ok: false,
+        issues: [
+          {
+            path: archivePath,
+            message: `archive exceeds max uncompressed size (${MAX_LKCOURSE_UNCOMPRESSED_BYTES} bytes)`
+          }
+        ]
+      };
+    }
+    entries.set(canonical, data);
+  }
+  if (issues.length) return { ok: false, issues };
+  return { ok: true, entries };
+}
+async function collectDistEntries(distDir, spaDistRelative) {
+  const { lstat: lstat2, readdir: readdir4, readFile: readFile2 } = await import("fs/promises");
+  const entries = /* @__PURE__ */ new Map();
+  const walk = async (absDir, relPrefix) => {
+    const dirEntries = await readdir4(absDir, { withFileTypes: true });
+    for (const entry of dirEntries) {
+      const abs = (0, import_node_path12.join)(absDir, entry.name);
+      const rel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+      const zipPath = `${spaDistRelative}/${rel}`.replace(/\\/g, "/");
+      if (!isSafeRelativeSpaPath(zipPath)) {
+        throw new Error(`unsafe dist path: ${zipPath}`);
+      }
+      const stat2 = await lstat2(abs);
+      if (stat2.isSymbolicLink()) {
+        throw new Error(`dist contains symlink: ${abs}`);
+      }
+      if (stat2.isDirectory()) {
+        await walk(abs, rel);
+      } else if (stat2.isFile()) {
+        entries.set(zipPath.replace(/\\/g, "/"), await readFile2(abs));
+      }
+    }
+  };
+  await walk(distDir, "");
+  return entries;
+}
+function entryToUtf8(data) {
+  return (0, import_fflate.strFromU8)(data);
+}
+function utf8ToEntry(text) {
+  return (0, import_fflate.strToU8)(text);
+}
+
+// src/lkcourse/parseEnvelope.ts
+function parseLkcourseEnvelope(raw, label = "manifest.json") {
+  const issues = [];
+  if (!raw || typeof raw !== "object") {
+    return { ok: false, issues: [{ path: label, message: "must be a JSON object" }] };
+  }
+  const obj = raw;
+  if (obj.format !== "lkcourse") {
+    issues.push({
+      path: "format",
+      message: `must be "lkcourse" (got ${String(obj.format)})`
+    });
+  }
+  let schemaVersion = obj.schemaVersion;
+  if (schemaVersion === "1") schemaVersion = 1;
+  if (schemaVersion !== 1) {
+    issues.push({
+      path: "schemaVersion",
+      message: `must be 1 (got ${String(obj.schemaVersion)})`
+    });
+  }
+  const lessonkitVersion = typeof obj.lessonkitVersion === "string" ? obj.lessonkitVersion.trim() : "";
+  if (!lessonkitVersion) {
+    issues.push({ path: "lessonkitVersion", message: "must be a non-empty string" });
+  }
+  const exportedAt = typeof obj.exportedAt === "string" ? obj.exportedAt.trim() : "";
+  if (!exportedAt) {
+    issues.push({ path: "exportedAt", message: "must be a non-empty string" });
+  }
+  const entriesRaw = obj.entries;
+  const entries = [];
+  if (!Array.isArray(entriesRaw) || entriesRaw.length === 0) {
+    issues.push({ path: "entries", message: "must be a non-empty array of relative paths" });
+  } else {
+    for (let i = 0; i < entriesRaw.length; i++) {
+      const entry = entriesRaw[i];
+      if (typeof entry !== "string" || !entry.trim()) {
+        issues.push({ path: `entries[${i}]`, message: "must be a non-empty string" });
+      } else {
+        const trimmed = entry.trim();
+        if (!isSafeZipEntryPath(trimmed)) {
+          issues.push({ path: `entries[${i}]`, message: "must be a safe relative path" });
+        } else {
+          entries.push(trimmed);
+        }
+      }
+    }
+  }
+  if (issues.length) return { ok: false, issues };
+  const manifestParsed = parseLessonkitManifest(obj.sourceManifest, `${label}.sourceManifest`);
+  if (!manifestParsed.ok) {
+    return {
+      ok: false,
+      issues: manifestParsed.issues.map((issue) => ({
+        path: `sourceManifest.${issue.path}`,
+        message: issue.message
+      }))
+    };
+  }
+  return {
+    ok: true,
+    envelope: {
+      format: "lkcourse",
+      schemaVersion: 1,
+      lessonkitVersion,
+      exportedAt,
+      sourceManifest: manifestParsed.manifest,
+      entries
+    }
+  };
+}
+
+// src/lkcourse/blockTree.ts
+var import_node_fs6 = require("fs");
+var import_node_module = require("module");
+var import_node_path13 = require("path");
+var import_core7 = require("@lessonkit/core");
+var import_meta = {};
+var SCANNABLE_EXTENSIONS2 = [".tsx", ".ts", ".jsx", ".js"];
+var ID_PROPS = ["courseId", "lessonId", "checkId", "blockId", "nodeId"];
+function stripComments2(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, " ");
+}
+function collectSourceUnderSrc2(projectRoot) {
+  const srcDir = (0, import_node_path13.join)(projectRoot, "src");
+  if (!(0, import_node_fs6.existsSync)(srcDir)) return [];
+  const results = [];
+  const walk = (dir) => {
+    for (const entry of (0, import_node_fs6.readdirSync)(dir)) {
+      const abs = (0, import_node_path13.join)(dir, entry);
+      try {
+        assertRealPathUnderRoot(projectRoot, abs);
+      } catch {
+        continue;
+      }
+      const stat2 = (0, import_node_fs6.lstatSync)(abs);
+      if (stat2.isSymbolicLink()) continue;
+      if (stat2.isDirectory()) {
+        walk(abs);
+      } else if (SCANNABLE_EXTENSIONS2.some((ext) => entry.endsWith(ext))) {
+        results.push((0, import_node_path13.relative)(projectRoot, abs));
+      }
+    }
+  };
+  walk(srcDir);
+  return results;
+}
+function loadCatalogBlockTypes(blockTypes) {
+  if (blockTypes?.length) return blockTypes;
+  try {
+    const require2 = (0, import_node_module.createRequire)(import_meta.url);
+    const catalogPath = require2.resolve("@lessonkit/react/block-catalog.v3.json");
+    const catalog = JSON.parse((0, import_node_fs6.readFileSync)(catalogPath, "utf8"));
+    return (catalog.entries ?? []).map((e) => e.type).filter((t) => typeof t === "string" && t.length > 0);
+  } catch {
+    return [
+      "Course",
+      "Lesson",
+      "Scenario",
+      "Quiz",
+      "KnowledgeCheck",
+      "ProgressTracker",
+      "Reflection",
+      "TrueFalse",
+      "MarkTheWords",
+      "FillInTheBlanks",
+      "DragTheWords",
+      "DragAndDrop",
+      "AssessmentSequence",
+      "Text",
+      "Heading",
+      "Image",
+      "Video",
+      "Page",
+      "InteractiveBook",
+      "Slide",
+      "SlideDeck",
+      "TimedCue",
+      "InteractiveVideo",
+      "Summary",
+      "BranchingScenario",
+      "BranchNode",
+      "BranchChoice",
+      "Embed",
+      "Chart"
+    ];
+  }
+}
+function extractIdProp(tagSource, prop) {
+  const re = new RegExp(
+    `\\b${prop}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|\\{\\s*["'\`]([^"'\`]+)["'\`]\\s*\\})`
+  );
+  const match = tagSource.match(re);
+  if (!match) return void 0;
+  return match[1] ?? match[2] ?? match[3];
+}
+function parseJsxBlocks(source, blockTypes) {
+  const stripped = stripComments2(source);
+  const tagRe = /<([A-Z][A-Za-z0-9]*)\b([^>]*?)(\/?)>/g;
+  const stack = [];
+  const roots = [];
+  for (const match of stripped.matchAll(tagRe)) {
+    const rawTag = match[1];
+    const attrs = match[2] ?? "";
+    const selfClosing = match[3] === "/";
+    if (rawTag === "Fragment" || rawTag.endsWith("Provider")) continue;
+    const known = blockTypes.has(rawTag);
+    const node = known ? { type: rawTag } : { type: "Unknown", rawTag };
+    for (const prop of ID_PROPS) {
+      const value = extractIdProp(attrs, prop);
+      if (value) node[prop] = value;
+    }
+    if (selfClosing) {
+      if (stack.length) {
+        const parent = stack[stack.length - 1];
+        parent.children = parent.children ?? [];
+        parent.children.push(node);
+      } else {
+        roots.push(node);
+      }
+      continue;
+    }
+    const closeRe = new RegExp(`</${rawTag}>`);
+    const closeMatch = closeRe.exec(stripped.slice((match.index ?? 0) + match[0].length));
+    if (!closeMatch) {
+      if (stack.length) {
+        const parent = stack[stack.length - 1];
+        parent.children = parent.children ?? [];
+        parent.children.push(node);
+      } else {
+        roots.push(node);
+      }
+      continue;
+    }
+    stack.push(node);
+    const nextClose = stripped.indexOf(`</${rawTag}>`, (match.index ?? 0) + match[0].length);
+    const inner = stripped.slice((match.index ?? 0) + match[0].length, nextClose);
+    if (!inner.includes("<")) {
+      stack.pop();
+      if (stack.length) {
+        const parent = stack[stack.length - 1];
+        parent.children = parent.children ?? [];
+        parent.children.push(node);
+      } else {
+        roots.push(node);
+      }
+    }
+  }
+  return roots.length ? roots : stack;
+}
+function validateNodeIds(node, pathPrefix, issues) {
+  for (const prop of ID_PROPS) {
+    const value = node[prop];
+    if (value === void 0) continue;
+    const validated = (0, import_core7.validateId)(value, prop);
+    if (!validated.ok) {
+      issues.push({
+        path: `${pathPrefix}.${prop}`,
+        message: validated.issues[0]?.message ?? `invalid ${prop}`
+      });
+    }
+  }
+  node.children?.forEach((child, index) => {
+    validateNodeIds(child, `${pathPrefix}.children[${index}]`, issues);
+  });
+}
+function validateBlockTreeIds(tree) {
+  const issues = [];
+  tree.blocks.forEach((block, index) => {
+    validateNodeIds(block, `blocks[${index}]`, issues);
+  });
+  return issues;
+}
+function extractBlockTree(options) {
+  const blockTypes = new Set(loadCatalogBlockTypes(options.blockTypes));
+  const sources = options.appSources ?? collectSourceUnderSrc2(options.projectRoot);
+  const blocks = [];
+  for (const rel of sources) {
+    const abs = (0, import_node_path13.join)(options.projectRoot, rel);
+    if (!(0, import_node_fs6.existsSync)(abs)) continue;
+    const source = (0, import_node_fs6.readFileSync)(abs, "utf8");
+    const parsed = parseJsxBlocks(source, blockTypes);
+    blocks.push(...parsed);
+  }
+  return {
+    schemaVersion: 1,
+    sources,
+    blocks
+  };
+}
+
+// src/lkcourse/export.ts
+var import_promises3 = require("fs/promises");
+var import_node_module2 = require("module");
+var import_node_path14 = require("path");
 var import_validators2 = require("@lxpack/validators");
+var import_meta2 = {};
+function resolveLessonkitVersion(explicit) {
+  if (explicit?.trim()) return explicit.trim();
+  try {
+    const require2 = (0, import_node_module2.createRequire)(import_meta2.url);
+    const pkg = require2("../../package.json");
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+async function exportLkcourse(options) {
+  const projectRoot = (0, import_node_path14.resolve)(options.projectRoot);
+  const manifest = options.manifest;
+  const spaDistDir = (0, import_node_path14.join)(projectRoot, manifest.paths.spaDistDir);
+  try {
+    assertRealPathUnderRoot(projectRoot, spaDistDir);
+    await assertSpaDistContentsSafe({ main: spaDistDir }, projectRoot);
+  } catch (err) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: manifest.paths.spaDistDir,
+          message: err instanceof Error ? err.message : String(err)
+        }
+      ]
+    };
+  }
+  const injectableIssues = validateInjectableAssessments(manifest.course);
+  if (injectableIssues.length > 0) {
+    return {
+      ok: false,
+      issues: injectableIssues.map((issue) => ({
+        path: issue.path,
+        message: issue.message
+      }))
+    };
+  }
+  const interchange = descriptorToInterchange(manifest.course);
+  const interchangeParsed = (0, import_validators2.parseLessonkitInterchange)(interchange);
+  if (!interchangeParsed.ok) {
+    return {
+      ok: false,
+      issues: interchangeParsed.issues.map((i) => ({
+        path: `interchange.${i.path ?? ""}`.replace(/\.$/, ""),
+        message: i.message
+      }))
+    };
+  }
+  const validatedInterchange = interchangeParsed.data;
+  const interchangeCourseId = validatedInterchange.course?.id;
+  if (!interchangeCourseId) {
+    return {
+      ok: false,
+      issues: [{ path: "interchange.course.id", message: "missing course id in interchange" }]
+    };
+  }
+  if (manifest.course.courseId !== interchangeCourseId) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: "course.courseId",
+          message: `descriptor courseId "${manifest.course.courseId}" does not match interchange course.id "${interchangeCourseId}"`
+        }
+      ]
+    };
+  }
+  const zipEntries = /* @__PURE__ */ new Map();
+  const interchangeJson = JSON.stringify(interchange, null, 2);
+  zipEntries.set("interchange.json", utf8ToEntry(interchangeJson));
+  let blockTreeJson;
+  if (options.includeBlockTree) {
+    const blockTree = extractBlockTree({ projectRoot });
+    const blockTreeIssues = validateBlockTreeIds(blockTree);
+    if (blockTreeIssues.length) {
+      return {
+        ok: false,
+        issues: blockTreeIssues.map((issue) => ({
+          path: `block-tree.${issue.path}`,
+          message: issue.message
+        }))
+      };
+    }
+    blockTreeJson = JSON.stringify(blockTree, null, 2);
+    zipEntries.set("block-tree.json", utf8ToEntry(blockTreeJson));
+  }
+  let distEntries;
+  try {
+    distEntries = await collectDistEntries(spaDistDir, manifest.paths.spaDistDir);
+  } catch (err) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: manifest.paths.spaDistDir,
+          message: err instanceof Error ? err.message : String(err)
+        }
+      ]
+    };
+  }
+  if (!distEntries.has(`${manifest.paths.spaDistDir}/index.html`.replace(/\\/g, "/"))) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: `${manifest.paths.spaDistDir}/index.html`,
+          message: "dist must contain index.html before export"
+        }
+      ]
+    };
+  }
+  for (const [path, data] of distEntries) {
+    zipEntries.set(path, data);
+  }
+  const entryPaths = [...zipEntries.keys()].sort();
+  const envelope = {
+    format: "lkcourse",
+    schemaVersion: 1,
+    lessonkitVersion: resolveLessonkitVersion(options.lessonkitVersion),
+    exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    sourceManifest: manifest,
+    entries: entryPaths
+  };
+  const envelopeCheck = parseLkcourseEnvelope(envelope);
+  if (!envelopeCheck.ok) {
+    return { ok: false, issues: envelopeCheck.issues };
+  }
+  zipEntries.set("manifest.json", utf8ToEntry(JSON.stringify(envelope, null, 2)));
+  const archivePath = (0, import_node_path14.resolve)(
+    projectRoot,
+    options.outPath ?? `${manifest.name}.lkcourse`
+  );
+  const archiveRel = options.outPath ?? `${manifest.name}.lkcourse`;
+  try {
+    assertRealPathUnderRoot(projectRoot, archivePath);
+  } catch (err) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: archiveRel,
+          message: err instanceof Error ? err.message : String(err)
+        }
+      ]
+    };
+  }
+  if (isReservedResolvedOutputPath(projectRoot, archivePath)) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: archiveRel,
+          message: "output path must not target reserved directories (.git, node_modules, .github)"
+        }
+      ]
+    };
+  }
+  if (!isSafeZipEntryPath(archiveRel)) {
+    return {
+      ok: false,
+      issues: [{ path: "outPath", message: "output path must be a safe relative path" }]
+    };
+  }
+  try {
+    await (0, import_promises3.mkdir)((0, import_node_path14.dirname)(archivePath), { recursive: true });
+    const zipped = createZip(zipEntries);
+    await (0, import_promises3.writeFile)(archivePath, zipped);
+  } catch (err) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: archivePath,
+          message: err instanceof Error ? err.message : String(err)
+        }
+      ]
+    };
+  }
+  return {
+    ok: true,
+    archivePath,
+    fileCount: zipEntries.size,
+    includeBlockTree: Boolean(options.includeBlockTree)
+  };
+}
+
+// src/lkcourse/validate.ts
+var import_validators3 = require("@lxpack/validators");
+
+// src/lkcourse/assessmentParity.ts
+function validateLkcourseAssessmentConsistency(descriptor, interchange) {
+  const issues = [];
+  for (const issue of validateInjectableAssessments(descriptor)) {
+    issues.push({
+      path: `sourceManifest.course.${issue.path}`,
+      message: issue.message
+    });
+  }
+  const expectedIds = extractAssessments(descriptor).map((a) => a.id).sort();
+  const interchangeIds = (interchange.assessments ?? []).map((a) => a.id).sort();
+  const matches = expectedIds.length === interchangeIds.length && expectedIds.every((id, index) => id === interchangeIds[index]);
+  if (!matches) {
+    issues.push({
+      path: "interchange.assessments",
+      message: `injectable assessment ids [${expectedIds.join(", ")}] do not match interchange [${interchangeIds.join(", ")}]`
+    });
+  }
+  return issues;
+}
+
+// src/lkcourse/validate.ts
+function validateLkcourseArchiveEntries(entries, _archiveLabel) {
+  const issues = [];
+  const manifestData = entries.get("manifest.json");
+  if (!manifestData) {
+    return {
+      ok: false,
+      issues: [{ path: "manifest.json", message: "required file missing from archive" }]
+    };
+  }
+  let envelopeRaw;
+  try {
+    envelopeRaw = JSON.parse(entryToUtf8(manifestData));
+  } catch {
+    return {
+      ok: false,
+      issues: [{ path: "manifest.json", message: "invalid JSON" }]
+    };
+  }
+  const envelopeParsed = parseLkcourseEnvelope(envelopeRaw, "manifest.json");
+  if (!envelopeParsed.ok) {
+    return { ok: false, issues: envelopeParsed.issues };
+  }
+  const envelope = envelopeParsed.envelope;
+  const interchangeData = entries.get("interchange.json");
+  if (!interchangeData) {
+    issues.push({ path: "interchange.json", message: "required file missing from archive" });
+  }
+  const spaDistDir = envelope.sourceManifest.paths.spaDistDir.replace(/\\/g, "/");
+  const spaIndexPath = `${spaDistDir}/index.html`;
+  if (!entries.has(spaIndexPath)) {
+    issues.push({ path: spaIndexPath, message: "required file missing from archive" });
+  }
+  const allowlisted = new Set(envelope.entries.map((entryPath) => entryPath.replace(/\\/g, "/")));
+  const spaDistPrefix = `${spaDistDir}/`;
+  for (const entryPath of envelope.entries) {
+    if (!entries.has(entryPath)) {
+      issues.push({
+        path: entryPath,
+        message: "listed in manifest.entries but missing from archive"
+      });
+    }
+  }
+  for (const zipPath of entries.keys()) {
+    const normalized = zipPath.replace(/\\/g, "/");
+    if (!normalized.startsWith(spaDistPrefix)) continue;
+    if (!allowlisted.has(normalized)) {
+      issues.push({
+        path: zipPath,
+        message: "unlisted file under spaDistDir; not in manifest.entries"
+      });
+    }
+  }
+  if (issues.length) return { ok: false, issues };
+  let interchangeRaw;
+  try {
+    interchangeRaw = JSON.parse(entryToUtf8(interchangeData));
+  } catch {
+    return {
+      ok: false,
+      issues: [{ path: "interchange.json", message: "invalid JSON" }]
+    };
+  }
+  const interchangeParsed = (0, import_validators3.parseLessonkitInterchange)(interchangeRaw);
+  if (!interchangeParsed.ok) {
+    return {
+      ok: false,
+      issues: interchangeParsed.issues.map((i) => ({
+        path: `interchange.${i.path ?? ""}`.replace(/\.$/, ""),
+        message: i.message
+      }))
+    };
+  }
+  const interchange = interchangeParsed.data;
+  const interchangeCourseId = interchange.course?.id;
+  if (!interchangeCourseId) {
+    issues.push({
+      path: "interchange.course.id",
+      message: "missing course id in interchange"
+    });
+  } else if (envelope.sourceManifest.course.courseId !== interchangeCourseId) {
+    issues.push({
+      path: "sourceManifest.course.courseId",
+      message: `does not match interchange.course.id (${interchangeCourseId})`
+    });
+  }
+  issues.push(
+    ...validateLkcourseAssessmentConsistency(
+      envelope.sourceManifest.course,
+      interchange
+    )
+  );
+  if (issues.length) return { ok: false, issues };
+  const blockTreeData = entries.get("block-tree.json");
+  if (blockTreeData) {
+    let blockTreeRaw;
+    try {
+      blockTreeRaw = JSON.parse(entryToUtf8(blockTreeData));
+    } catch {
+      return {
+        ok: false,
+        issues: [{ path: "block-tree.json", message: "invalid JSON" }]
+      };
+    }
+    const blockTree = blockTreeRaw;
+    if (Array.isArray(blockTree?.blocks)) {
+      const blockTreeIssues = validateBlockTreeIds(blockTree);
+      if (blockTreeIssues.length) {
+        return {
+          ok: false,
+          issues: blockTreeIssues.map((issue) => ({
+            path: `block-tree.${issue.path}`,
+            message: issue.message
+          }))
+        };
+      }
+    }
+  }
+  return {
+    ok: true,
+    envelope,
+    interchange
+  };
+}
+function validateLkcourse(archivePath) {
+  const read = readZip(archivePath);
+  if (!read.ok) return read;
+  return validateLkcourseArchiveEntries(read.entries, archivePath);
+}
+
+// src/lkcourse/import.ts
+var import_promises4 = require("fs/promises");
+var import_node_path15 = require("path");
+var IMPORT_ARTIFACTS = ["lessonkit.json", "dist"];
+async function pathExists2(path) {
+  try {
+    await (0, import_promises4.access)(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function renameOrCopy2(from, to, opts) {
+  const renameFn = opts?.renameFn ?? import_promises4.rename;
+  try {
+    await renameFn(from, to);
+  } catch (err) {
+    const code = err && typeof err === "object" && "code" in err ? String(err.code) : "";
+    if (code !== "EXDEV") throw err;
+    await (0, import_promises4.cp)(from, to, { recursive: true });
+    await (0, import_promises4.rm)(from, { recursive: true, force: true });
+  }
+}
+async function writeImportTree(stagingDir, manifest, entries, spaDistDir, allowlistedSpaPaths) {
+  let fileCount = 0;
+  await (0, import_promises4.writeFile)(
+    (0, import_node_path15.join)(stagingDir, "lessonkit.json"),
+    `${JSON.stringify(manifest, null, 2)}
+`,
+    "utf8"
+  );
+  fileCount += 1;
+  for (const [entryPath, data] of entries) {
+    const normalized = entryPath.replace(/\\/g, "/");
+    if (!normalized.startsWith(`${spaDistDir}/`)) continue;
+    if (!allowlistedSpaPaths.has(normalized)) {
+      throw new Error(`unlisted spaDist entry rejected: ${entryPath}`);
+    }
+    const relativeUnderSpa = normalized.slice(spaDistDir.length + 1);
+    const outPath = (0, import_node_path15.join)(stagingDir, spaDistDir, relativeUnderSpa);
+    const resolvedOut = (0, import_node_path15.resolve)(outPath);
+    assertRealPathUnderRoot(stagingDir, resolvedOut);
+    if (!isSafeZipEntryPath((0, import_node_path15.join)(spaDistDir, relativeUnderSpa))) {
+      throw new Error(`unsafe extraction path: ${entryPath}`);
+    }
+    await (0, import_promises4.mkdir)((0, import_node_path15.dirname)(resolvedOut), { recursive: true });
+    await (0, import_promises4.writeFile)(resolvedOut, data);
+    fileCount += 1;
+  }
+  return fileCount;
+}
+async function backupImportArtifacts(targetDir) {
+  const existing = [];
+  for (const name of IMPORT_ARTIFACTS) {
+    if (await pathExists2((0, import_node_path15.join)(targetDir, name))) {
+      existing.push(name);
+    }
+  }
+  if (!existing.length) return void 0;
+  const backupDir = await (0, import_promises4.mkdtemp)((0, import_node_path15.join)(targetDir, ".lkcourse-backup-"));
+  for (const name of existing) {
+    await renameOrCopy2((0, import_node_path15.join)(targetDir, name), (0, import_node_path15.join)(backupDir, name));
+  }
+  return backupDir;
+}
+async function restoreImportBackup(targetDir, backupDir) {
+  for (const name of IMPORT_ARTIFACTS) {
+    const backupPath = (0, import_node_path15.join)(backupDir, name);
+    if (!await pathExists2(backupPath)) continue;
+    const destPath = (0, import_node_path15.join)(targetDir, name);
+    if (await pathExists2(destPath)) {
+      await (0, import_promises4.rm)(destPath, { recursive: true, force: true });
+    }
+    await renameOrCopy2(backupPath, destPath);
+  }
+}
+async function snapshotPreExistingImportArtifacts(targetDir) {
+  const existing = /* @__PURE__ */ new Set();
+  for (const name of IMPORT_ARTIFACTS) {
+    if (await pathExists2((0, import_node_path15.join)(targetDir, name))) {
+      existing.add(name);
+    }
+  }
+  return existing;
+}
+async function rollbackFailedImport(targetDir, backupDir, preExisting) {
+  if (backupDir) {
+    await restoreImportBackup(targetDir, backupDir);
+  }
+  for (const name of IMPORT_ARTIFACTS) {
+    if (preExisting.has(name)) continue;
+    const destPath = (0, import_node_path15.join)(targetDir, name);
+    if (await pathExists2(destPath)) {
+      await (0, import_promises4.rm)(destPath, { recursive: true, force: true });
+    }
+  }
+}
+async function promoteImportStaging(stagingDir, targetDir) {
+  await (0, import_promises4.mkdir)(targetDir, { recursive: true });
+  const entries = await (0, import_promises4.readdir)(stagingDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = (0, import_node_path15.join)(stagingDir, entry.name);
+    const destPath = (0, import_node_path15.join)(targetDir, entry.name);
+    if (entry.isDirectory() || entry.isFile()) {
+      await renameOrCopy2(srcPath, destPath);
+    }
+  }
+}
+var promoteImportStagingImpl = promoteImportStaging;
+async function importLkcourse(options) {
+  const archivePath = (0, import_node_path15.resolve)(options.archivePath);
+  const targetDir = (0, import_node_path15.resolve)(options.targetDir);
+  const validated = validateLkcourse(archivePath);
+  if (!validated.ok) return validated;
+  const { envelope, interchange } = validated;
+  const manifest = envelope.sourceManifest;
+  const spaDistDir = manifest.paths.spaDistDir.replace(/\\/g, "/");
+  try {
+    await (0, import_promises4.mkdir)(targetDir, { recursive: true });
+    assertRealPathUnderRoot(targetDir, targetDir);
+  } catch (err) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: targetDir,
+          message: err instanceof Error ? err.message : String(err)
+        }
+      ]
+    };
+  }
+  const read = readZip(archivePath);
+  if (!read.ok) return read;
+  let stagingDir;
+  let backupDir;
+  let preExisting;
+  try {
+    stagingDir = await (0, import_promises4.mkdtemp)((0, import_node_path15.join)(targetDir, ".lkcourse-import-"));
+    const allowlistedSpaPaths = new Set(
+      envelope.entries.map((entryPath) => entryPath.replace(/\\/g, "/")).filter((entryPath) => entryPath.startsWith(`${spaDistDir}/`))
+    );
+    const fileCount = await writeImportTree(
+      stagingDir,
+      manifest,
+      read.entries,
+      spaDistDir,
+      allowlistedSpaPaths
+    );
+    preExisting = await snapshotPreExistingImportArtifacts(targetDir);
+    backupDir = await backupImportArtifacts(targetDir);
+    try {
+      await promoteImportStagingImpl(stagingDir, targetDir);
+    } catch (promoteError) {
+      await rollbackFailedImport(targetDir, backupDir, preExisting);
+      backupDir = void 0;
+      throw promoteError;
+    }
+    if (backupDir) {
+      await (0, import_promises4.rm)(backupDir, { recursive: true, force: true }).catch(() => void 0);
+      backupDir = void 0;
+    }
+    await (0, import_promises4.rm)(stagingDir, { recursive: true, force: true });
+    stagingDir = void 0;
+    return {
+      ok: true,
+      targetDir,
+      manifest,
+      interchange,
+      fileCount
+    };
+  } catch (err) {
+    if (preExisting) {
+      await rollbackFailedImport(targetDir, backupDir, preExisting).catch(() => void 0);
+    } else if (backupDir) {
+      await restoreImportBackup(targetDir, backupDir).catch(() => void 0);
+    }
+    if (backupDir) {
+      await (0, import_promises4.rm)(backupDir, { recursive: true, force: true }).catch(() => void 0);
+    }
+    if (stagingDir) {
+      await (0, import_promises4.rm)(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+    }
+    return {
+      ok: false,
+      issues: [
+        {
+          path: targetDir,
+          message: err instanceof Error ? err.message : String(err)
+        }
+      ]
+    };
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   LESSONKIT_TELEMETRY_EVENTS,
+  assertSpaDistContentsSafe,
   assessmentDescriptorToLxpack,
   buildLessonkitProject,
   buildStagingPackage,
   descriptorToInterchange,
   ensureOutDirParent,
   escapeShellText,
+  exportLkcourse,
   extractAssessments,
+  extractBlockTree,
+  importLkcourse,
   lessonkitInterchangeSchema,
   loadLessonkitManifestFromFile,
   mapLessonkitIds,
@@ -2193,6 +3481,7 @@ var import_validators2 = require("@lxpack/validators");
   packageLessonkitCourse,
   parseLessonkitInterchange,
   parseLessonkitManifest,
+  parseLkcourseEnvelope,
   promoteStagingToOutDir,
   remapArtifactPaths,
   resolveSafePackageOutputOverride,
@@ -2202,6 +3491,9 @@ var import_validators2 = require("@lxpack/validators");
   validateDescriptor,
   validateDescriptorForTarget,
   validateLessonkitProject,
+  validateLkcourse,
+  validateLkcourseArchiveEntries,
+  validateManifestName,
   validatePackageInputs,
   validateProjectPaths,
   validateReactManifestParity,