@lessonkit/lxpack 1.4.0 → 1.6.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   telemetryEventToLessonkit
-} from "./chunk-DYQI222N.js";
+} from "./chunk-HTZR4CF3.js";
 
 // src/descriptor/normalize.ts
 import { validateId } from "@lessonkit/core";
@@ -99,10 +99,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") {
@@ -280,6 +288,98 @@ function isResolvedPathUnderRoot(root, target) {
   return !rel.startsWith("..") && !isAbsolute(rel);
 }
 
+// src/validateProjectPaths.ts
+import { existsSync as existsSync2, realpathSync as realpathSync2 } from "fs";
+import { isAbsolute as isAbsolute2, resolve as resolve2 } from "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 isReservedResolvedOutputPath(projectRoot, resolved) {
+  const rootResolved = resolveComparablePath(projectRoot);
+  const targetResolved = resolveComparablePath(resolved);
+  try {
+    const rootReal = existsSync2(rootResolved) ? realpathSync2(rootResolved) : rootResolved;
+    const targetReal = existsSync2(targetResolved) ? realpathSync2(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, resolve2(projectRoot, value));
+  } catch {
+    issues.push({
+      path: fieldPath,
+      message: "path must resolve inside the project root"
+    });
+  }
+}
+function validateProjectPaths(projectRoot, paths) {
+  const issues = [];
+  const root = resolve2(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 = resolve2(projectRoot);
+  const trimmed = override.trim();
+  if (!trimmed) {
+    throw new Error("output override must be a non-empty path");
+  }
+  if (isAbsolute2(trimmed)) {
+    const resolved2 = resolve2(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 = resolve2(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
 import { getPresetTheme, themeToCssVariables } from "@lessonkit/themes";
 function themeToLxpackRuntime(input) {
@@ -344,8 +444,52 @@ var ASSESSMENT_VALIDATORS = {
     }
   },
   fillInBlanks: (assessment, path, issues) => {
-    if (assessment.kind === "fillInBlanks" && !assessment.template?.trim()) {
+    if (assessment.kind !== "fillInBlanks") return;
+    if (!assessment.template?.trim()) {
       issues.push({ path: `${path}.template`, message: "template is required for fillInBlanks" });
+      return;
+    }
+    const templateBlankCount = countStarDelimitedBlanks(assessment.template);
+    if (templateBlankCount === 0) {
+      issues.push({
+        path: `${path}.template`,
+        message: "template must include at least one blank wrapped in asterisks for fillInBlanks"
+      });
+    }
+    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"
+      });
+    }
+    if (explicitBlanks.length > 0 && explicitBlanks.length !== templateBlankCount) {
+      issues.push({
+        path: `${path}.blanks`,
+        message: `blanks length (${explicitBlanks.length}) must match template blank count (${templateBlankCount})`
+      });
     }
   },
   findHotspot: (assessment, path, issues) => {
@@ -483,6 +627,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",
@@ -543,27 +701,49 @@ function validateCourseDescriptor(input) {
 }
 
 // src/assessments.ts
+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;");
+}
+function decodeShellEntities(text) {
+  return text.replace(/&amp;/gi, "&").replace(/&lt;/gi, "<").replace(/&gt;/gi, ">").replace(/&quot;/gi, '"').replace(/&#39;/gi, "'").replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16))).replace(/&#(\d+);/g, (_, num) => String.fromCharCode(Number(num)));
+}
+function containsUnsafeShellMarkup(text) {
+  const decoded = decodeShellEntities(text);
+  return /<\/script/i.test(decoded) || /<!--/.test(decoded) || /<[a-zA-Z!/]/.test(decoded);
+}
+function sanitizeShellField(text) {
+  if (containsUnsafeShellMarkup(text)) return null;
+  return escapeShellText(text);
+}
 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 checkId = sanitizeShellField(assessment.checkId);
+  const prompt = sanitizeShellField(assessment.question);
+  if (!checkId || !prompt) return null;
+  const normalizedAnswer = assessment.answer.trim();
   const choices = assessment.choices.map((text, index) => {
+    const sanitizedText = sanitizeShellField(text);
+    if (!sanitizedText) return null;
     const id = slugChoiceId(text, index);
     return {
       id,
-      text,
-      correct: text === assessment.answer
+      text: sanitizedText,
+      correct: text.trim() === normalizedAnswer
     };
   });
+  if (choices.some((choice) => choice === null)) return null;
   return {
-    id: assessment.checkId,
-    passingScore: assessment.passingScore ?? 1,
+    id: checkId,
+    passingScore: assessment.passingScore ?? DEFAULT_SHELL_PASSING_SCORE,
     questions: [
       {
         id: "q1",
-        prompt: assessment.question,
+        prompt,
         choices
       }
     ]
@@ -604,11 +784,14 @@ function extractAssessments(descriptor) {
 // src/descriptor/validateInjectableAssessments.ts
 function validateInjectableAssessments(descriptor) {
   const issues = [];
+  const spaOnlyKinds = /* @__PURE__ */ new Set(["fillInBlanks", "findHotspot", "findMultipleHotspots"]);
   (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}`
       });
     }
   });
@@ -623,22 +806,29 @@ var LMS_SHELL_TARGETS = /* @__PURE__ */ new Set([
   "xapi",
   "cmi5"
 ]);
+function appendActivityIriIssues(issues, descriptor, target) {
+  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();
+  const targetSuffix = target === "xapi" || target === "cmi5" ? ` for ${target} export targets` : " when tracking.xapi is configured";
+  if (!activityIri) {
+    issues.push({
+      path: "tracking.xapi.activityIri",
+      message: `tracking.xapi.activityIri is required${targetSuffix}`
+    });
+    return;
+  }
+  if (!/^https:\/\/.+/i.test(activityIri)) {
+    issues.push({
+      path: "tracking.xapi.activityIri",
+      message: `tracking.xapi.activityIri must be an HTTPS URL${targetSuffix}`
+    });
+  }
+}
 function validateDescriptorForExportTarget(descriptor, target) {
   const issues = [];
-  if (target === "xapi" || target === "cmi5") {
-    const activityIri = descriptor.tracking?.xapi?.activityIri?.trim();
-    if (!activityIri) {
-      issues.push({
-        path: "tracking.xapi.activityIri",
-        message: "tracking.xapi.activityIri is required for xapi and cmi5 export targets"
-      });
-    } else if (!/^https:\/\/.+/i.test(activityIri)) {
-      issues.push({
-        path: "tracking.xapi.activityIri",
-        message: "tracking.xapi.activityIri must be an HTTPS URL for xapi and cmi5 export targets"
-      });
-    }
-  }
+  appendActivityIriIssues(issues, descriptor, target);
   if (LMS_SHELL_TARGETS.has(target)) {
     issues.push(...validateInjectableAssessments(descriptor).map((issue) => ({
       ...issue,
@@ -672,19 +862,53 @@ function validateDescriptorForTarget(input, target) {
 }
 
 // src/validateReactParity.ts
-import { readFileSync, existsSync as existsSync2, readdirSync, statSync } from "fs";
+import { readFileSync, existsSync as existsSync3, readdirSync, lstatSync } from "fs";
 import { join as join2, relative as relative2 } from "path";
 var SCANNABLE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
-function collectSourceUnderSrc(projectRoot) {
+function collectSourceUnderSrc(projectRoot, issues) {
   const srcDir = join2(projectRoot, "src");
-  if (!existsSync2(srcDir)) return [];
+  if (!existsSync3(srcDir)) return [];
   const results = [];
   const walk = (dir) => {
     for (const entry of readdirSync(dir)) {
       const abs = join2(dir, entry);
-      if (statSync(abs).isDirectory()) {
+      let stat2;
+      try {
+        stat2 = lstatSync(abs);
+      } catch {
+        continue;
+      }
+      if (stat2.isSymbolicLink()) {
+        issues.push({
+          path: relative2(projectRoot, abs),
+          message: `Source tree contains symlink (rejected for parity scan): ${relative2(projectRoot, abs)}`,
+          severity: "error"
+        });
+        continue;
+      }
+      if (stat2.isDirectory()) {
+        try {
+          assertRealPathUnderRoot(projectRoot, abs);
+        } catch {
+          issues.push({
+            path: relative2(projectRoot, abs),
+            message: `Source directory escapes project root: ${relative2(projectRoot, abs)}`,
+            severity: "error"
+          });
+          continue;
+        }
         walk(abs);
       } else if (SCANNABLE_EXTENSIONS.some((ext) => entry.endsWith(ext))) {
+        try {
+          assertRealPathUnderRoot(projectRoot, abs);
+        } catch {
+          issues.push({
+            path: relative2(projectRoot, abs),
+            message: `Source file escapes project root: ${relative2(projectRoot, abs)}`,
+            severity: "error"
+          });
+          continue;
+        }
         results.push(relative2(projectRoot, abs));
       }
     }
@@ -692,20 +916,69 @@ function collectSourceUnderSrc(projectRoot) {
   walk(srcDir);
   return results;
 }
-function readAppSources(projectRoot, appSources) {
-  return appSources.map((rel) => join2(projectRoot, rel)).filter((abs) => existsSync2(abs)).map((abs) => readFileSync(abs, "utf8")).join("\n");
+function readAppSources(projectRoot, appSources, issues, customSourcesProvided) {
+  return appSources.map((rel) => {
+    if (!isSafeRelativeSpaPath(rel)) {
+      if (customSourcesProvided) {
+        issues.push({
+          path: rel,
+          message: `Unsafe appSources path skipped: ${rel}`,
+          severity: "warning"
+        });
+      }
+      return null;
+    }
+    const abs = join2(projectRoot, rel);
+    try {
+      assertRealPathUnderRoot(projectRoot, abs);
+      if (existsSync3(abs) && lstatSync(abs).isSymbolicLink()) {
+        issues.push({
+          path: rel,
+          message: `appSources path is a symlink: ${rel}`,
+          severity: "error"
+        });
+        return null;
+      }
+    } catch {
+      issues.push({
+        path: rel,
+        message: `appSources path escapes project root: ${rel}`,
+        severity: "error"
+      });
+      return null;
+    }
+    if (!existsSync3(abs)) return null;
+    return readFileSync(abs, "utf8");
+  }).filter((content) => content != null).join("\n");
 }
 function stripComments(source) {
   return source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, " ");
 }
-function idPropPatterns(prop, id) {
-  return [
-    `${prop}="${id}"`,
-    `${prop}='${id}'`,
-    `${prop}={'${id}'}`,
-    `${prop}={"${id}"}`,
-    `${prop}={\`${id}\`}`
-  ];
+function maskUnrelatedStringLiterals(source) {
+  return source.replace(/(["'`])(?:\\.|(?!\1).)*\1/g, (match, _quote, offset, full) => {
+    const before = full.slice(Math.max(0, offset - 24), offset);
+    if (/\b(?:courseId|checkId|lessonId)\s*=\s*$/.test(before)) {
+      return match;
+    }
+    return '""';
+  });
+}
+function idPropPresent(source, prop, id) {
+  const stripped = stripComments(source);
+  const masked = maskUnrelatedStringLiterals(stripped);
+  return jsxPropRegex(prop, id).test(masked);
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function jsxPropRegex(prop, id) {
+  const escapedId = escapeRegExp(id);
+  return new RegExp(
+    `(?<![A-Za-z0-9_$])${prop}\\s*=\\s*(?:"${escapedId}"|'${escapedId}'|\\{\\s*["'\`]${escapedId}["'\`]\\s*\\}|\\{\\s*\`${escapedId}\`\\s*\\})`
+  );
+}
+function maskStringLiterals(source) {
+  return source.replace(/(["'`])(?:\\.|(?!\1).)*\1/g, '""');
 }
 function extractStringConstants(source) {
   const stripped = stripComments(source);
@@ -716,7 +989,9 @@ function extractStringConstants(source) {
   }
   return map;
 }
-function idUsedViaConstant(stripped, prop, id, constants) {
+function idUsedViaConstant(source, prop, id, constants) {
+  const stripped = stripComments(source);
+  const masked = maskStringLiterals(stripped);
   for (const [name, value] of constants) {
     if (value !== id) continue;
     const jsxPatterns = [
@@ -725,40 +1000,72 @@ function idUsedViaConstant(stripped, prop, id, constants) {
       `${prop}={${name} }`,
       `${prop}={ ${name}}`
     ];
-    if (jsxPatterns.some((p) => stripped.includes(p))) return true;
-    const objPatterns = [`${prop}: ${name}`, `${prop}:${name}`];
-    if (objPatterns.some((p) => stripped.includes(p))) return true;
+    if (jsxPatterns.some((p) => masked.includes(p))) return true;
   }
   return false;
 }
-function courseIdPresent(source, courseId) {
+function lessonIdInDataLiteral(source, lessonId) {
   const stripped = stripComments(source);
-  if (idPropPatterns("courseId", courseId).some((p) => stripped.includes(p))) return true;
-  return idUsedViaConstant(stripped, "courseId", courseId, extractStringConstants(source));
+  const escaped = escapeRegExp(lessonId);
+  return new RegExp(`\\bid\\s*:\\s*["'\`]${escaped}["'\`]`).test(stripped);
 }
-function checkIdPresent(source, checkId) {
+function lessonIdPresent(source, lessonId) {
+  if (idPropPresent(source, "lessonId", lessonId)) return true;
+  if (idUsedViaConstant(source, "lessonId", lessonId, extractStringConstants(source))) return true;
+  return lessonIdInDataLiteral(source, lessonId);
+}
+function courseConfigCourseIdPresent(source, courseId) {
+  const stripped = stripComments(source);
+  const escaped = escapeRegExp(courseId);
+  const literalPattern = new RegExp(
+    `(?<![A-Za-z0-9_$])courseId\\s*:\\s*(?:"${escaped}"|'${escaped}')`
+  );
+  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);
-  if (idPropPatterns("checkId", checkId).some((p) => stripped.includes(p))) return true;
-  return idUsedViaConstant(stripped, "checkId", checkId, extractStringConstants(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) {
+  if (idPropPresent(source, "checkId", checkId)) return true;
+  return idUsedViaConstant(source, "checkId", checkId, extractStringConstants(source));
 }
 var ID_SYNC_DOC = "https://lessonkit.readthedocs.io/en/latest/guides/react-developers/quickstart.html#keep-react-ids-in-sync-with-lessonkitjson";
 function parityHint(message) {
   return `${message} See ${ID_SYNC_DOC}`;
 }
 function validateReactManifestParity(opts) {
-  const appSources = opts.appSources ?? collectSourceUnderSrc(opts.projectRoot);
-  const source = readAppSources(opts.projectRoot, appSources);
+  const issues = [];
+  const customSourcesProvided = opts.appSources !== void 0;
+  const appSources = opts.appSources ?? collectSourceUnderSrc(opts.projectRoot, issues);
+  const source = readAppSources(
+    opts.projectRoot,
+    appSources,
+    issues,
+    customSourcesProvided
+  );
   const hasDescriptorIds = Boolean(opts.descriptor.courseId) || (opts.descriptor.assessments?.length ?? 0) > 0;
   if (!source.trim()) {
-    return [
-      {
-        path: appSources.length > 0 ? appSources.join(", ") : "src/",
-        message: hasDescriptorIds ? "React app source not found for ID parity check" : "React app source not found for ID parity check",
-        severity: hasDescriptorIds ? "error" : "warning"
-      }
-    ];
+    issues.push({
+      path: appSources.length > 0 ? appSources.join(", ") : "src/",
+      message: hasDescriptorIds ? "React app source required for ID parity check when descriptor defines courseId or assessments" : "React app source not found for ID parity check",
+      severity: hasDescriptorIds ? "error" : "warning"
+    });
+    return issues;
   }
-  const issues = [];
   const courseId = opts.descriptor.courseId;
   if (!courseIdPresent(source, courseId)) {
     issues.push({
@@ -769,6 +1076,19 @@ function validateReactManifestParity(opts) {
       severity: "error"
     });
   }
+  for (const lesson of opts.descriptor.lessons ?? []) {
+    const lessonId = lesson.id;
+    if (!lessonId) continue;
+    if (!lessonIdPresent(source, lessonId)) {
+      issues.push({
+        path: `lessons.id:${lessonId}`,
+        message: parityHint(
+          `React app source missing lessonId="${lessonId}" declared in lessonkit.json.`
+        ),
+        severity: "error"
+      });
+    }
+  }
   for (const assessment of opts.descriptor.assessments ?? []) {
     const checkId = assessment.checkId;
     if (!checkId) continue;
@@ -785,58 +1105,6 @@ function validateReactManifestParity(opts) {
   return issues;
 }
 
-// src/validateProjectPaths.ts
-import { isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
-function validatePathField(value, fieldPath, projectRoot, issues) {
-  if (!isSafeRelativeSpaPath(value)) {
-    issues.push({
-      path: fieldPath,
-      message: "path must be relative without '..' segments or absolute prefixes"
-    });
-    return;
-  }
-  try {
-    assertRealPathUnderRoot(projectRoot, resolve2(projectRoot, value));
-  } catch {
-    issues.push({
-      path: fieldPath,
-      message: "path must resolve inside the project root"
-    });
-  }
-}
-function validateProjectPaths(projectRoot, paths) {
-  const issues = [];
-  const root = resolve2(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);
-  }
-  if (paths.outputBaseDir?.trim()) {
-    validatePathField(paths.outputBaseDir.trim(), "paths.outputBaseDir", root, issues);
-  }
-  return issues;
-}
-function resolveSafePackageOutputOverride(projectRoot, override) {
-  const root = resolve2(projectRoot);
-  const trimmed = override.trim();
-  if (!trimmed) {
-    throw new Error("output override must be a non-empty path");
-  }
-  if (isAbsolute2(trimmed)) {
-    const resolved2 = resolve2(trimmed);
-    assertRealPathUnderRoot(root, resolved2);
-    return resolved2;
-  }
-  if (!isSafeRelativeSpaPath(trimmed)) {
-    throw new Error(`unsafe output path: ${override}`);
-  }
-  const resolved = resolve2(root, trimmed);
-  assertRealPathUnderRoot(root, resolved);
-  return resolved;
-}
-
 // src/mapIds.ts
 import { assertValidId } from "@lessonkit/core";
 function mapLessonkitIds(descriptor) {
@@ -968,7 +1236,7 @@ async function resolveSpaDirs(options) {
 
 // src/spaDistValidation.ts
 import { lstat, readdir } from "fs/promises";
-import { realpathSync as realpathSync2 } from "fs";
+import { realpathSync as realpathSync3 } from "fs";
 import { join as join4 } from "path";
 async function assertSpaDistContentsSafe(spaDirs, projectRoot) {
   for (const [label, dir] of Object.entries(spaDirs)) {
@@ -979,7 +1247,7 @@ async function assertSpaDistContentsSafe(spaDirs, projectRoot) {
     }
     let rootReal;
     try {
-      rootReal = realpathSync2(dirResolved);
+      rootReal = realpathSync3(dirResolved);
     } catch {
       throw new Error(`spa dist for "${label}" is not readable: ${dir}`);
     }
@@ -1008,9 +1276,12 @@ async function walkDistDir(rootReal, current, label) {
     }
     let entryReal;
     try {
-      entryReal = realpathSync2(entryPath);
-    } catch {
-      entryReal = entryPath;
+      entryReal = realpathSync3(entryPath);
+    } catch (err) {
+      throw new Error(
+        `spa dist for "${label}" could not resolve path: ${entryPath}`,
+        { cause: err }
+      );
     }
     assertResolvedPathUnderRoot(rootReal, entryReal);
     if (stat2.isDirectory()) {
@@ -1030,12 +1301,12 @@ 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 = resolve4(options.outDir);
-  if (options.projectRoot) {
-    assertRealPathUnderRoot(resolve4(options.projectRoot), outDir);
-  }
+  assertRealPathUnderRoot(resolve4(options.projectRoot), outDir);
   const spaDirs = await resolveSpaDirs({ ...options, descriptor });
   await assertSpaDistContentsSafe(spaDirs, options.projectRoot);
   const interchange = descriptorToInterchange(descriptor);
@@ -1098,6 +1369,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,
@@ -1155,6 +1439,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 = isAbsolute3(output) ? resolve5(output) : resolve5(projectRoot, output);
@@ -1176,22 +1473,51 @@ function validatePackageInputs(options) {
         ]
       };
     }
-  }
-  return { ok: true, outDir, projectRoot };
-}
-function validateArtifactInStaging(stagingRoot, artifactPath, field) {
-  if (!artifactPath) return null;
-  const resolved = resolveComparablePath(artifactPath);
-  if (!isResolvedPathUnderRoot(stagingRoot, resolved)) {
-    return {
-      path: field,
-      message: `${field} is outside the staging directory: ${artifactPath}`
-    };
-  }
-  return null;
-}
-function remapArtifactPaths(stagingRoot, outDir, artifactPath) {
-  if (!artifactPath) return void 0;
+    const outputRel = isAbsolute3(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)"
+          }
+        ]
+      };
+    }
+    try {
+      relativePathUnderRoot(outDir, resolvedOutput);
+    } catch {
+      return {
+        ok: false,
+        courseDir: outDir,
+        target,
+        issues: [
+          {
+            path: "output",
+            message: "output must resolve inside outDir"
+          }
+        ]
+      };
+    }
+  }
+  return { ok: true, outDir, projectRoot };
+}
+function validateArtifactInStaging(stagingRoot, artifactPath, field) {
+  if (!artifactPath) return null;
+  const resolved = resolveComparablePath(artifactPath);
+  if (!isResolvedPathUnderRoot(stagingRoot, resolved)) {
+    return {
+      path: field,
+      message: `${field} is outside the staging directory: ${artifactPath}`
+    };
+  }
+  return null;
+}
+function remapArtifactPaths(stagingRoot, outDir, artifactPath) {
+  if (!artifactPath) return void 0;
   const resolved = resolveComparablePath(artifactPath);
   if (!isResolvedPathUnderRoot(stagingRoot, resolved)) {
     throw new Error(`${artifactPath} is outside the staging directory`);
@@ -1234,33 +1560,53 @@ function promoteLockPath(outDir) {
   const hash = createHash("sha256").update(resolve6(outDir)).digest("hex").slice(0, 16);
   return join7(parent, `.lk-promote-lock-${hash}`);
 }
-var STALE_LOCK_TTL_MS = 5 * 60 * 1e3;
+var STALE_ARTIFACT_TTL_MS = 5 * 60 * 1e3;
+var MAX_LOCK_AGE_MS = 30 * 60 * 1e3;
+var LOCK_TOKEN_RE = /^(\d+)\n([0-9a-f-]{36})(?:\n(\d+))?\n?$/i;
 async function isStalePromoteLock(lockPath) {
   try {
+    const stat2 = await fsp.stat(lockPath);
     const content = await fsp.readFile(lockPath, "utf8");
-    const pid = Number.parseInt(content.trim(), 10);
-    if (Number.isFinite(pid) && pid > 0) {
-      try {
-        process.kill(pid, 0);
-        return false;
-      } catch {
-        return true;
+    const match = content.match(LOCK_TOKEN_RE);
+    let lockAgeMs = Date.now() - stat2.mtimeMs;
+    if (match?.[3]) {
+      const startedAt = Number.parseInt(match[3], 10);
+      if (Number.isFinite(startedAt) && startedAt > 0) {
+        lockAgeMs = Date.now() - startedAt;
       }
     }
-    const stat2 = await fsp.stat(lockPath);
-    return Date.now() - stat2.mtimeMs > STALE_LOCK_TTL_MS;
+    if (lockAgeMs > MAX_LOCK_AGE_MS) {
+      return true;
+    }
+    if (match) {
+      const pid = Number.parseInt(match[1], 10);
+      if (Number.isFinite(pid) && pid > 0) {
+        try {
+          process.kill(pid, 0);
+          return false;
+        } catch {
+          return true;
+        }
+      }
+    }
+    return lockAgeMs > STALE_ARTIFACT_TTL_MS;
   } catch {
     return true;
   }
 }
+var PROMOTE_LOCK_TIMEOUT_MS = 15e3;
 async function withPromoteLock(outDir, fn) {
   const lockPath = promoteLockPath(outDir);
   await fsp.mkdir(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}
+${randomUUID()}
+${Date.now()}
 `, "utf8");
       break;
     } catch (err) {
@@ -1273,7 +1619,9 @@ async function withPromoteLock(outDir, fn) {
         );
         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) {
@@ -1292,22 +1640,77 @@ async function withPromoteLock(outDir, fn) {
     );
   }
 }
-async function assertNoLegacyPromoteArtifacts(outDir) {
+async function removeStaleLegacyPromoteArtifacts(outDir) {
   const legacyTmp = `${outDir}.tmp-promote`;
   const legacyBak = `${outDir}.bak`;
-  const stale = [];
-  if (await pathExists(legacyTmp)) stale.push(legacyTmp);
-  if (await pathExists(legacyBak)) stale.push(legacyBak);
-  if (stale.length) {
+  const blocked = [];
+  for (const legacyPath of [legacyTmp, legacyBak]) {
+    if (!await pathExists(legacyPath)) continue;
+    try {
+      const stat2 = await fsp.stat(legacyPath);
+      if (Date.now() - stat2.mtimeMs > STALE_ARTIFACT_TTL_MS) {
+        await fsp.rm(legacyPath, { recursive: true, force: true }).catch(
+          /* v8 ignore next */
+          () => void 0
+        );
+        continue;
+      }
+    } catch {
+    }
+    blocked.push(legacyPath);
+  }
+  if (blocked.length) {
+    const rmHint = blocked.map((p) => `rm -rf ${JSON.stringify(p)}`).join("; ");
     throw new Error(
-      `[lessonkit/lxpack] cannot promote: remove stale packaging artifacts from a previous failed run: ${stale.join(", ")}`
+      `[lessonkit/lxpack] cannot promote: remove stale packaging artifacts from a previous failed run: ${blocked.join(", ")}. Try: ${rmHint}`
     );
   }
 }
-async function promoteStagingToOutDir(stagingDir, outDir) {
+async function listRelativePaths(root, dir = root) {
+  const entries = await fsp.readdir(dir, { withFileTypes: true });
+  const paths = [];
+  for (const entry of entries) {
+    const full = join7(dir, entry.name);
+    if (entry.isDirectory()) {
+      paths.push(...await listRelativePaths(root, full));
+    } else if (entry.isFile()) {
+      paths.push(full.slice(root.length + 1));
+    } else {
+    }
+  }
+  return paths;
+}
+async function mergePreservedOutArtifacts(priorArtifactsDir, destArtifactsDir, newArtifactPaths) {
+  if (!await pathExists(priorArtifactsDir)) return;
+  for (const rel of await listRelativePaths(priorArtifactsDir)) {
+    if (newArtifactPaths.has(rel)) continue;
+    const src = join7(priorArtifactsDir, rel);
+    const dest = join7(destArtifactsDir, rel);
+    await fsp.mkdir(dirname(dest), { recursive: true });
+    await fsp.cp(src, dest, { force: true });
+  }
+}
+async function promoteStagingToOutDir(stagingDir, outDir, options) {
+  const outputBaseDir = options?.outputBaseDir ?? ".lxpack/out";
+  if (options?.projectRoot) {
+    assertRealPathUnderRoot(resolve6(options.projectRoot), resolve6(outDir));
+  }
   return withPromoteLock(outDir, async () => {
-    await assertNoLegacyPromoteArtifacts(outDir);
+    await removeStaleLegacyPromoteArtifacts(outDir);
+    const stagingArtifactsDir = join7(stagingDir, outputBaseDir);
+    const newArtifactPaths = /* @__PURE__ */ new Set();
+    if (await pathExists(stagingArtifactsDir)) {
+      for (const rel of await listRelativePaths(stagingArtifactsDir)) {
+        newArtifactPaths.add(rel);
+      }
+    }
     const parent = dirname(outDir);
+    let priorArtifactsBackup;
+    const existingArtifactsDir = join7(outDir, outputBaseDir);
+    if (await pathExists(outDir) && await pathExists(existingArtifactsDir)) {
+      priorArtifactsBackup = await fsp.mkdtemp(join7(parent, ".lk-prior-out-"));
+      await fsp.cp(existingArtifactsDir, join7(priorArtifactsBackup, outputBaseDir), { recursive: true });
+    }
     const tmpPromote = await fsp.mkdtemp(join7(parent, ".lk-promote-"));
     await renameOrCopy(stagingDir, tmpPromote);
     const hadOutDir = await pathExists(outDir);
@@ -1364,6 +1767,20 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
       }
       throw promoteError;
     }
+    if (priorArtifactsBackup) {
+      try {
+        await mergePreservedOutArtifacts(
+          join7(priorArtifactsBackup, outputBaseDir),
+          join7(outDir, outputBaseDir),
+          newArtifactPaths
+        );
+      } finally {
+        await fsp.rm(priorArtifactsBackup, { recursive: true, force: true }).catch(
+          /* v8 ignore next */
+          () => void 0
+        );
+      }
+    }
     if (backup) {
       await fsp.rm(backup, { recursive: true, force: true }).catch(
         /* v8 ignore next */
@@ -1381,6 +1798,7 @@ import { packageLessonkit } from "@lxpack/api";
 async function buildStagingPackage(options) {
   const { target, output, dir, outputBaseDir, descriptor, ...writeOpts } = options;
   const stagingDir = await fsp2.mkdtemp(join8(tmpdir(), "lessonkit-lxpack-"));
+  let succeeded = false;
   try {
     let spaDirs;
     try {
@@ -1436,6 +1854,7 @@ async function buildStagingPackage(options) {
         }))
       };
     }
+    succeeded = true;
     return {
       ok: true,
       stagingDir,
@@ -1449,6 +1868,13 @@ async function buildStagingPackage(options) {
       () => void 0
     );
     throw err;
+  } finally {
+    if (!succeeded) {
+      await fsp2.rm(stagingDir, { recursive: true, force: true }).catch(
+        /* v8 ignore next */
+        () => void 0
+      );
+    }
   }
 }
 async function ensureOutDirParent(outDir) {
@@ -1463,6 +1889,12 @@ 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) {
@@ -1513,33 +1945,46 @@ async function packageLessonkitCourse(options) {
     };
   }
   const descriptor = descriptorValidation.descriptor;
-  if (writeOpts.projectRoot) {
-    const parityIssues = validateReactManifestParity({
-      projectRoot: writeOpts.projectRoot,
-      descriptor
+  const parityIssues = validateReactManifestParity({
+    projectRoot: writeOpts.projectRoot,
+    descriptor
+  });
+  const parityFailures = writeOpts.strictParity ? parityIssues : parityIssues.filter((i) => i.severity === "error");
+  if (parityFailures.length > 0) {
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      issues: parityFailures.map((i) => ({
+        path: i.path,
+        message: i.message,
+        severity: i.severity
+      }))
+    };
+  }
+  let staged;
+  try {
+    staged = await buildStagingPackage({
+      ...writeOpts,
+      descriptor,
+      target,
+      output,
+      dir,
+      outputBaseDir
     });
-    const parityErrors = parityIssues.filter((i) => i.severity === "error");
-    if (parityErrors.length > 0) {
-      return {
-        ok: false,
-        courseDir: outDir,
-        target,
-        issues: parityErrors.map((i) => ({
-          path: i.path,
-          message: i.message,
-          severity: i.severity
-        }))
-      };
-    }
+  } catch (err) {
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      issues: [
+        {
+          path: "staging",
+          message: err instanceof Error ? err.message : String(err)
+        }
+      ]
+    };
   }
-  const staged = await buildStagingPackage({
-    ...writeOpts,
-    descriptor,
-    target,
-    output,
-    dir,
-    outputBaseDir
-  });
   if (!staged.ok) {
     await fsp3.rm(staged.stagingDir, { recursive: true, force: true }).catch(
       /* v8 ignore next */
@@ -1589,11 +2034,30 @@ async function packageLessonkitCourse(options) {
       ok: false,
       courseDir: outDir,
       target,
-      validation: { ok: true, manifest: build.manifest, issues: build.issues },
+      validation: { ok: false, manifest: build.manifest, issues: build.issues },
       build,
       issues: artifactIssues
     };
   }
+  const buildWarningIssues = findPackagingWarningIssues(build.issues);
+  if (options.strictBuild && buildWarningIssues.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: buildWarningIssues.map((i) => ({
+        path: i.path ?? "build",
+        message: i.message ?? "build warning",
+        severity: i.severity
+      }))
+    };
+  }
   const remappedOutputPath = remapArtifactPaths(stagingRoot, outDir, staged.outputPath);
   const remappedOutputDir = remapArtifactPaths(stagingRoot, outDir, staged.outputDir);
   const validation = {
@@ -1603,7 +2067,10 @@ async function packageLessonkitCourse(options) {
   };
   try {
     await ensureOutDirParent(outDir);
-    await promoteStagingToOutDir(stagingDir, outDir);
+    await promoteStagingToOutDir(stagingDir, outDir, {
+      outputBaseDir: outputBaseDir ?? ".lxpack/out",
+      projectRoot: writeOpts.projectRoot
+    });
   } catch (err) {
     await fsp3.rm(stagingDir, { recursive: true, force: true }).catch(
       /* v8 ignore next */
@@ -1726,6 +2193,20 @@ function parseLessonkitManifest(raw, label = "lessonkit.json", projectRoot) {
       message: `"course.spaDistDir" (${courseSpaDistDir}) differs from "paths.spaDistDir" (${paths.spaDistDir}). Use paths.spaDistDir for CLI build and package.`
     });
   }
+  for (const key of ["spaDistDir", "lxpackOutDir", "outputBaseDir"]) {
+    const value = paths[key];
+    if (!isSafeRelativeSpaPath(value)) {
+      issues.push({
+        path: `paths.${key}`,
+        message: "path must be relative without '..' segments or absolute prefixes"
+      });
+    } else if (isReservedOutputPath(value)) {
+      issues.push({
+        path: `paths.${key}`,
+        message: "path must not target reserved directories (.git, node_modules, .github)"
+      });
+    }
+  }
   if (projectRoot) {
     const pathIssues = validateProjectPaths(projectRoot, paths);
     for (const pi of pathIssues) {
@@ -1761,16 +2242,821 @@ import {
 import {
   lessonkitInterchangeSchema,
   materializeLessonkitProject as materializeLessonkitProject2,
-  parseLessonkitInterchange
+  parseLessonkitInterchange as parseLessonkitInterchange3
 } from "@lxpack/validators";
+
+// src/lkcourse/zip.ts
+import { readFileSync as readFileSync2, statSync } from "fs";
+import { dirname as dirname3, join as join9, normalize } from "path";
+import { strFromU8, strToU8, unzipSync, zipSync } from "fflate";
+var MAX_LKCOURSE_UNCOMPRESSED_BYTES = 256 * 1024 * 1024;
+function canonicalZipEntryPath(entryPath) {
+  const slashNormalized = entryPath.replace(/\\/g, "/");
+  const canonical = 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 zipSync(zipped, { level: 6 });
+}
+function readZip(archivePath) {
+  const issues = [];
+  let raw;
+  try {
+    raw = readFileSync2(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 = 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 = join9(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 strFromU8(data);
+}
+function utf8ToEntry(text) {
+  return 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
+import { existsSync as existsSync4, lstatSync as lstatSync2, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "fs";
+import { createRequire } from "module";
+import { join as join10, relative as relative3 } from "path";
+import { validateId as validateId4 } from "@lessonkit/core";
+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 = join10(projectRoot, "src");
+  if (!existsSync4(srcDir)) return [];
+  const results = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync2(dir)) {
+      const abs = join10(dir, entry);
+      try {
+        assertRealPathUnderRoot(projectRoot, abs);
+      } catch {
+        continue;
+      }
+      const stat2 = lstatSync2(abs);
+      if (stat2.isSymbolicLink()) continue;
+      if (stat2.isDirectory()) {
+        walk(abs);
+      } else if (SCANNABLE_EXTENSIONS2.some((ext) => entry.endsWith(ext))) {
+        results.push(relative3(projectRoot, abs));
+      }
+    }
+  };
+  walk(srcDir);
+  return results;
+}
+function loadCatalogBlockTypes(blockTypes) {
+  if (blockTypes?.length) return blockTypes;
+  try {
+    const require2 = createRequire(import.meta.url);
+    const catalogPath = require2.resolve("@lessonkit/react/block-catalog.v3.json");
+    const catalog = JSON.parse(readFileSync3(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 = validateId4(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 = join10(options.projectRoot, rel);
+    if (!existsSync4(abs)) continue;
+    const source = readFileSync3(abs, "utf8");
+    const parsed = parseJsxBlocks(source, blockTypes);
+    blocks.push(...parsed);
+  }
+  return {
+    schemaVersion: 1,
+    sources,
+    blocks
+  };
+}
+
+// src/lkcourse/export.ts
+import { mkdir as mkdir3, writeFile } from "fs/promises";
+import { createRequire as createRequire2 } from "module";
+import { dirname as dirname4, join as join11, resolve as resolve8 } from "path";
+import { parseLessonkitInterchange } from "@lxpack/validators";
+function resolveLessonkitVersion(explicit) {
+  if (explicit?.trim()) return explicit.trim();
+  try {
+    const require2 = createRequire2(import.meta.url);
+    const pkg = require2("../../package.json");
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+async function exportLkcourse(options) {
+  const projectRoot = resolve8(options.projectRoot);
+  const manifest = options.manifest;
+  const spaDistDir = join11(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 interchange = descriptorToInterchange(manifest.course);
+  const interchangeParsed = 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 = resolve8(
+    projectRoot,
+    options.outPath ?? `${manifest.name}.lkcourse`
+  );
+  try {
+    assertRealPathUnderRoot(projectRoot, archivePath);
+  } catch (err) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: options.outPath ?? `${manifest.name}.lkcourse`,
+          message: err instanceof Error ? err.message : String(err)
+        }
+      ]
+    };
+  }
+  if (!isSafeZipEntryPath(options.outPath ?? `${manifest.name}.lkcourse`)) {
+    return {
+      ok: false,
+      issues: [{ path: "outPath", message: "output path must be a safe relative path" }]
+    };
+  }
+  try {
+    await mkdir3(dirname4(archivePath), { recursive: true });
+    const zipped = createZip(zipEntries);
+    await 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
+import { parseLessonkitInterchange as parseLessonkitInterchange2 } from "@lxpack/validators";
+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" });
+  }
+  for (const entryPath of envelope.entries) {
+    if (!entries.has(entryPath)) {
+      issues.push({
+        path: entryPath,
+        message: "listed in manifest.entries but missing from archive"
+      });
+    }
+  }
+  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 = parseLessonkitInterchange2(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})`
+    });
+  }
+  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
+import { access as access3, cp as cp2, mkdir as mkdir4, mkdtemp as mkdtemp3, readdir as readdir3, rename as rename2, rm as rm4, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname5, join as join12, resolve as resolve9 } from "path";
+var IMPORT_ARTIFACTS = ["lessonkit.json", "dist"];
+async function pathExists2(path) {
+  try {
+    await access3(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function renameOrCopy2(from, to, opts) {
+  const renameFn = opts?.renameFn ?? rename2;
+  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 cp2(from, to, { recursive: true });
+    await rm4(from, { recursive: true, force: true });
+  }
+}
+async function writeImportTree(stagingDir, manifest, entries, spaDistDir) {
+  let fileCount = 0;
+  await writeFile2(
+    join12(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;
+    const relativeUnderSpa = normalized.slice(spaDistDir.length + 1);
+    const outPath = join12(stagingDir, spaDistDir, relativeUnderSpa);
+    const resolvedOut = resolve9(outPath);
+    assertRealPathUnderRoot(stagingDir, resolvedOut);
+    if (!isSafeZipEntryPath(join12(spaDistDir, relativeUnderSpa))) {
+      throw new Error(`unsafe extraction path: ${entryPath}`);
+    }
+    await mkdir4(dirname5(resolvedOut), { recursive: true });
+    await writeFile2(resolvedOut, data);
+    fileCount += 1;
+  }
+  return fileCount;
+}
+async function backupImportArtifacts(targetDir) {
+  const existing = [];
+  for (const name of IMPORT_ARTIFACTS) {
+    if (await pathExists2(join12(targetDir, name))) {
+      existing.push(name);
+    }
+  }
+  if (!existing.length) return void 0;
+  const backupDir = await mkdtemp3(join12(targetDir, ".lkcourse-backup-"));
+  for (const name of existing) {
+    await renameOrCopy2(join12(targetDir, name), join12(backupDir, name));
+  }
+  return backupDir;
+}
+async function restoreImportBackup(targetDir, backupDir) {
+  for (const name of IMPORT_ARTIFACTS) {
+    const backupPath = join12(backupDir, name);
+    if (!await pathExists2(backupPath)) continue;
+    const destPath = join12(targetDir, name);
+    if (await pathExists2(destPath)) {
+      await rm4(destPath, { recursive: true, force: true });
+    }
+    await renameOrCopy2(backupPath, destPath);
+  }
+}
+async function promoteImportStaging(stagingDir, targetDir) {
+  const entries = await readdir3(stagingDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join12(stagingDir, entry.name);
+    const destPath = join12(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      await cp2(srcPath, destPath, { recursive: true, force: true });
+    } else if (entry.isFile()) {
+      await mkdir4(dirname5(destPath), { recursive: true });
+      await cp2(srcPath, destPath);
+    }
+  }
+}
+var promoteImportStagingImpl = promoteImportStaging;
+async function importLkcourse(options) {
+  const archivePath = resolve9(options.archivePath);
+  const targetDir = resolve9(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 mkdir4(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;
+  try {
+    stagingDir = await mkdtemp3(join12(targetDir, ".lkcourse-import-"));
+    const fileCount = await writeImportTree(stagingDir, manifest, read.entries, spaDistDir);
+    backupDir = await backupImportArtifacts(targetDir);
+    try {
+      await promoteImportStagingImpl(stagingDir, targetDir);
+    } catch (promoteError) {
+      if (backupDir) {
+        await restoreImportBackup(targetDir, backupDir);
+      }
+      throw promoteError;
+    }
+    if (backupDir) {
+      await rm4(backupDir, { recursive: true, force: true }).catch(() => void 0);
+      backupDir = void 0;
+    }
+    await rm4(stagingDir, { recursive: true, force: true });
+    stagingDir = void 0;
+    return {
+      ok: true,
+      targetDir,
+      manifest,
+      interchange,
+      fileCount
+    };
+  } catch (err) {
+    if (backupDir) {
+      await restoreImportBackup(targetDir, backupDir).catch(() => void 0);
+      await rm4(backupDir, { recursive: true, force: true }).catch(() => void 0);
+    }
+    if (stagingDir) {
+      await rm4(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+    }
+    return {
+      ok: false,
+      issues: [
+        {
+          path: targetDir,
+          message: err instanceof Error ? err.message : String(err)
+        }
+      ]
+    };
+  }
+}
 export {
   LESSONKIT_TELEMETRY_EVENTS,
+  assertSpaDistContentsSafe,
   assessmentDescriptorToLxpack,
   buildLessonkitProject,
   buildStagingPackage,
   descriptorToInterchange,
   ensureOutDirParent,
+  escapeShellText,
+  exportLkcourse,
   extractAssessments,
+  extractBlockTree,
+  importLkcourse,
   lessonkitInterchangeSchema,
   loadLessonkitManifestFromFile,
   mapLessonkitIds,
@@ -1778,8 +3064,9 @@ export {
   mapLessonkitTelemetryToLxpack,
   materializeLessonkitProject2 as materializeLessonkitProject,
   packageLessonkitCourse,
-  parseLessonkitInterchange,
+  parseLessonkitInterchange3 as parseLessonkitInterchange,
   parseLessonkitManifest,
+  parseLkcourseEnvelope,
   promoteStagingToOutDir,
   remapArtifactPaths,
   resolveSafePackageOutputOverride,
@@ -1789,6 +3076,8 @@ export {
   validateDescriptor,
   validateDescriptorForTarget,
   validateLessonkitProject,
+  validateLkcourse,
+  validateLkcourseArchiveEntries,
   validatePackageInputs,
   validateProjectPaths,
   validateReactManifestParity,