@lessonkit/lxpack 1.6.0 → 1.7.0

package/dist/index.js

@@ -62,13 +62,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)
       };
     })
   };
@@ -142,7 +169,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,
@@ -154,7 +204,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) {
@@ -202,8 +260,8 @@ import { validateId as validateId3 } from "@lessonkit/core";
 import { validateTheme } from "@lessonkit/themes";
 
 // src/spaPath.ts
-import { existsSync, realpathSync } from "fs";
-import { isAbsolute, join, relative, resolve, sep, win32 } from "path";
+import { realpathSync } from "fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32 } from "path";
 function resolveComparablePath(p) {
   if (/^[a-zA-Z]:[/\\]/.test(p)) {
     return win32.resolve(p);
@@ -229,43 +287,32 @@ function assertResolvedPathUnderRoot(root, target) {
     throw new Error(`unsafe path escapes project root: ${target}`);
   }
 }
-function resolveExistingPathUnderRoot(rootReal, rootResolved, targetResolved) {
-  const rel = relative(rootResolved, targetResolved);
-  if (rel.startsWith("..") || rel.includes(`..${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 = join(current, segment);
-    if (existsSync(next)) {
+function resolvePhysicalPathForCheck(p) {
+  const resolved = resolveComparablePath(p);
+  try {
+    return realpathSync.native(resolved);
+  } catch {
+    let probe = resolved;
+    let suffix = "";
+    while (true) {
       try {
-        current = realpathSync(next);
+        const physical = realpathSync.native(probe);
+        return suffix ? join(physical, suffix) : physical;
       } catch {
-        current = next;
+        if (probe === dirname(probe)) {
+          return resolved;
+        }
+        const segment = basename(probe);
+        suffix = suffix ? join(segment, suffix) : segment;
+        probe = 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 = realpathSync(rootResolved);
-  } catch {
-    rootReal = rootResolved;
-  }
-  try {
-    const targetCheck = 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);
@@ -289,7 +336,7 @@ function isResolvedPathUnderRoot(root, target) {
 }
 
 // src/validateProjectPaths.ts
-import { existsSync as existsSync2, realpathSync as realpathSync2 } from "fs";
+import { existsSync, 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) {
@@ -299,12 +346,27 @@ function isReservedOutputPath(value) {
   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 = existsSync2(rootResolved) ? realpathSync2(rootResolved) : rootResolved;
-    const targetReal = existsSync2(targetResolved) ? realpathSync2(targetResolved) : targetResolved;
+    const rootReal = existsSync(rootResolved) ? realpathSync2(rootResolved) : rootResolved;
+    const targetReal = existsSync(targetResolved) ? realpathSync2(targetResolved) : targetResolved;
     const rel = relativePathUnderRoot(rootReal, targetReal);
     return isReservedOutputPath(rel);
   } catch {
@@ -397,6 +459,7 @@ function themeToLxpackRuntime(input) {
 
 // src/descriptor/validateAssessments.ts
 import { validateId as validateId2 } from "@lessonkit/core";
+import { isMultiSelectMcq } from "@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" });
@@ -412,9 +475,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 && 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" });
@@ -434,6 +532,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 = {
@@ -519,7 +623,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}]`;
@@ -701,6 +829,7 @@ function validateCourseDescriptor(input) {
 }
 
 // src/assessments.ts
+import { isMultiSelectMcq as isMultiSelectMcq2 } from "@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;");
@@ -726,6 +855,7 @@ function mcqToLxpack(assessment) {
   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;
@@ -733,17 +863,21 @@ function mcqToLxpack(assessment) {
     return {
       id,
       text: sanitizedText,
-      correct: text.trim() === normalizedAnswer
+      correct: multiCorrect.has(text.trim())
     };
   });
   if (choices.some((choice) => choice === null)) return null;
+  const multiSelect = isMultiSelectMcq2(assessment);
   return {
     id: checkId,
     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
       }
     ]
@@ -772,7 +906,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;
@@ -784,7 +931,13 @@ function extractAssessments(descriptor) {
 // src/descriptor/validateInjectableAssessments.ts
 function validateInjectableAssessments(descriptor) {
   const issues = [];
-  const spaOnlyKinds = /* @__PURE__ */ new Set(["fillInBlanks", "findHotspot", "findMultipleHotspots"]);
+  const spaOnlyKinds = /* @__PURE__ */ new Set([
+    "fillInBlanks",
+    "findHotspot",
+    "findMultipleHotspots",
+    "sortParagraphs",
+    "guessTheAnswer"
+  ]);
   (descriptor.assessments ?? []).forEach((assessment, index) => {
     if (assessmentDescriptorToLxpack(assessment) === null) {
       const kind = assessment.kind ?? "mcq";
@@ -862,12 +1015,12 @@ function validateDescriptorForTarget(input, target) {
 }
 
 // src/validateReactParity.ts
-import { readFileSync, existsSync as existsSync3, readdirSync, lstatSync } from "fs";
+import { readFileSync, existsSync as existsSync2, readdirSync, lstatSync } from "fs";
 import { join as join2, relative as relative2 } from "path";
 var SCANNABLE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
 function collectSourceUnderSrc(projectRoot, issues) {
   const srcDir = join2(projectRoot, "src");
-  if (!existsSync3(srcDir)) return [];
+  if (!existsSync2(srcDir)) return [];
   const results = [];
   const walk = (dir) => {
     for (const entry of readdirSync(dir)) {
@@ -931,7 +1084,7 @@ function readAppSources(projectRoot, appSources, issues, customSourcesProvided)
     const abs = join2(projectRoot, rel);
     try {
       assertRealPathUnderRoot(projectRoot, abs);
-      if (existsSync3(abs) && lstatSync(abs).isSymbolicLink()) {
+      if (existsSync2(abs) && lstatSync(abs).isSymbolicLink()) {
         issues.push({
           path: rel,
           message: `appSources path is a symlink: ${rel}`,
@@ -947,7 +1100,7 @@ function readAppSources(projectRoot, appSources, issues, customSourcesProvided)
       });
       return null;
     }
-    if (!existsSync3(abs)) return null;
+    if (!existsSync2(abs)) return null;
     return readFileSync(abs, "utf8");
   }).filter((content) => content != null).join("\n");
 }
@@ -1330,8 +1483,8 @@ async function writeLxpackProject(options) {
 }
 
 // src/packageCourse.ts
-import { resolve as resolve7 } from "path";
-import * as fsp3 from "fs/promises";
+import { resolve as resolve9 } from "path";
+import * as fsp4 from "fs/promises";
 import {
   buildCourse,
   validateCourse
@@ -1487,21 +1640,6 @@ function validatePackageInputs(options) {
         ]
       };
     }
-    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 };
 }
@@ -1536,7 +1674,7 @@ function remapArtifactPaths(stagingRoot, outDir, artifactPath) {
 // src/packaging/promote.ts
 import * as fsp from "fs/promises";
 import { createHash, randomUUID } from "crypto";
-import { dirname, join as join7, resolve as resolve6 } from "path";
+import { dirname as dirname2, join as join7, resolve as resolve6 } from "path";
 async function pathExists(path) {
   try {
     await fsp.access(path);
@@ -1556,7 +1694,7 @@ async function renameOrCopy(from, to) {
   }
 }
 function promoteLockPath(outDir) {
-  const parent = dirname(outDir);
+  const parent = dirname2(outDir);
   const hash = createHash("sha256").update(resolve6(outDir)).digest("hex").slice(0, 16);
   return join7(parent, `.lk-promote-lock-${hash}`);
 }
@@ -1597,7 +1735,7 @@ async function isStalePromoteLock(lockPath) {
 var PROMOTE_LOCK_TIMEOUT_MS = 15e3;
 async function withPromoteLock(outDir, fn) {
   const lockPath = promoteLockPath(outDir);
-  await fsp.mkdir(dirname(outDir), { recursive: true });
+  await fsp.mkdir(dirname2(outDir), { recursive: true });
   let lockHandle;
   const maxAttempts = 400;
   const started = Date.now();
@@ -1686,7 +1824,7 @@ async function mergePreservedOutArtifacts(priorArtifactsDir, destArtifactsDir, n
     if (newArtifactPaths.has(rel)) continue;
     const src = join7(priorArtifactsDir, rel);
     const dest = join7(destArtifactsDir, rel);
-    await fsp.mkdir(dirname(dest), { recursive: true });
+    await fsp.mkdir(dirname2(dest), { recursive: true });
     await fsp.cp(src, dest, { force: true });
   }
 }
@@ -1704,7 +1842,7 @@ async function promoteStagingToOutDir(stagingDir, outDir, options) {
         newArtifactPaths.add(rel);
       }
     }
-    const parent = dirname(outDir);
+    const parent = dirname2(outDir);
     let priorArtifactsBackup;
     const existingArtifactsDir = join7(outDir, outputBaseDir);
     if (await pathExists(outDir) && await pathExists(existingArtifactsDir)) {
@@ -1790,14 +1928,29 @@ async function promoteStagingToOutDir(stagingDir, outDir, options) {
   });
 }
 
-// src/packaging/staging.ts
+// src/packaging/relocateOutput.ts
 import * as fsp2 from "fs/promises";
-import { dirname as dirname2, join as join8 } from "path";
+import { dirname as dirname3, resolve as resolve7 } from "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 = resolve7(projectRoot);
+  assertRealPathUnderRoot(root, resolvedRequested);
+  await fsp2.mkdir(dirname3(resolvedRequested), { recursive: true });
+  await renameOrCopy(resolvedBuilt, resolvedRequested);
+  return resolvedRequested;
+}
+
+// src/packaging/staging.ts
+import * as fsp3 from "fs/promises";
+import { dirname as dirname4, isAbsolute as isAbsolute4, join as join8, resolve as resolve8 } from "path";
 import { tmpdir } from "os";
 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-"));
+  const stagingDir = await fsp3.mkdtemp(join8(tmpdir(), "lessonkit-lxpack-"));
   let succeeded = false;
   try {
     let spaDirs;
@@ -1829,14 +1982,28 @@ async function buildStagingPackage(options) {
     }
     const interchange = descriptorToInterchange(descriptor);
     const outputBase = outputBaseDir ?? ".lxpack/out";
-    await fsp2.mkdir(join8(stagingDir, outputBase), { recursive: true });
-    const defaultOutput = output ?? (dir ? join8(outputBase, target) : join8(outputBase, `course-${target}.zip`));
+    await fsp3.mkdir(join8(stagingDir, outputBase), { recursive: true });
+    const defaultOutput = dir ? join8(outputBase, target) : join8(outputBase, `course-${target}.zip`);
+    let packageOutput = output ?? defaultOutput;
+    let requestedOutputPath;
+    let requestedOutputDir;
+    if (output) {
+      const projectRoot = resolve8(writeOpts.projectRoot);
+      const requested = isAbsolute4(output) ? resolve8(output) : resolve8(projectRoot, output);
+      if (dir) {
+        requestedOutputDir = requested;
+        packageOutput = defaultOutput;
+      } else {
+        requestedOutputPath = requested;
+        packageOutput = defaultOutput;
+      }
+    }
     const build = await packageLessonkit({
       interchange,
       spaDirs,
       target,
       courseDir: stagingDir,
-      output: defaultOutput,
+      output: packageOutput,
       dir,
       outputBaseDir,
       outputAnchorDir: stagingDir,
@@ -1860,17 +2027,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
       );
@@ -1878,7 +2047,7 @@ async function buildStagingPackage(options) {
   }
 }
 async function ensureOutDirParent(outDir) {
-  await fsp2.mkdir(dirname2(outDir), { recursive: true });
+  await fsp3.mkdir(dirname4(outDir), { recursive: true });
 }
 
 // src/packaging/issueSeverity.ts
@@ -1899,13 +2068,13 @@ function findPackagingWarningIssues(issues) {
 // src/packageCourse.ts
 async function validateLessonkitProject(options) {
   return validateCourse({
-    courseDir: resolve7(options.courseDir),
+    courseDir: resolve9(options.courseDir),
     target: options.target
   });
 }
 async function buildLessonkitProject(options) {
   const buildOptions = {
-    courseDir: resolve7(options.courseDir),
+    courseDir: resolve9(options.courseDir),
     target: options.target,
     output: options.output,
     dir: options.dir,
@@ -1936,7 +2105,7 @@ async function packageLessonkitCourse(options) {
   if (!descriptorValidation.ok) {
     return {
       ok: false,
-      courseDir: resolve7(writeOpts.outDir),
+      courseDir: resolve9(writeOpts.outDir),
       target,
       issues: descriptorValidation.issues.map((i) => ({
         path: i.path,
@@ -1986,7 +2155,7 @@ async function packageLessonkitCourse(options) {
     };
   }
   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
     );
@@ -2003,7 +2172,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
     );
@@ -2020,13 +2189,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
     );
@@ -2041,7 +2210,7 @@ async function packageLessonkitCourse(options) {
   }
   const buildWarningIssues = findPackagingWarningIssues(build.issues);
   if (options.strictBuild && buildWarningIssues.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
     );
@@ -2058,8 +2227,8 @@ async function packageLessonkitCourse(options) {
       }))
     };
   }
-  const remappedOutputPath = remapArtifactPaths(stagingRoot, outDir, staged.outputPath);
-  const remappedOutputDir = remapArtifactPaths(stagingRoot, outDir, staged.outputDir);
+  let remappedOutputPath = remapArtifactPaths(stagingRoot, outDir, staged.outputPath);
+  let remappedOutputDir = remapArtifactPaths(stagingRoot, outDir, staged.outputDir);
   const validation = {
     ok: true,
     manifest: build.manifest,
@@ -2072,7 +2241,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
     );
@@ -2090,6 +2259,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;
@@ -2133,8 +2328,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)) {
@@ -2247,7 +2443,7 @@ import {
 
 // src/lkcourse/zip.ts
 import { readFileSync as readFileSync2, statSync } from "fs";
-import { dirname as dirname3, join as join9, normalize } from "path";
+import { dirname as dirname5, join as join9, normalize } from "path";
 import { strFromU8, strToU8, unzipSync, zipSync } from "fflate";
 var MAX_LKCOURSE_UNCOMPRESSED_BYTES = 256 * 1024 * 1024;
 function canonicalZipEntryPath(entryPath) {
@@ -2427,7 +2623,7 @@ function parseLkcourseEnvelope(raw, label = "manifest.json") {
 }
 
 // src/lkcourse/blockTree.ts
-import { existsSync as existsSync4, lstatSync as lstatSync2, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync3, 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";
@@ -2438,7 +2634,7 @@ function stripComments2(source) {
 }
 function collectSourceUnderSrc2(projectRoot) {
   const srcDir = join10(projectRoot, "src");
-  if (!existsSync4(srcDir)) return [];
+  if (!existsSync3(srcDir)) return [];
   const results = [];
   const walk = (dir) => {
     for (const entry of readdirSync2(dir)) {
@@ -2592,7 +2788,7 @@ function extractBlockTree(options) {
   const blocks = [];
   for (const rel of sources) {
     const abs = join10(options.projectRoot, rel);
-    if (!existsSync4(abs)) continue;
+    if (!existsSync3(abs)) continue;
     const source = readFileSync3(abs, "utf8");
     const parsed = parseJsxBlocks(source, blockTypes);
     blocks.push(...parsed);
@@ -2605,9 +2801,9 @@ function extractBlockTree(options) {
 }
 
 // src/lkcourse/export.ts
-import { mkdir as mkdir3, writeFile } from "fs/promises";
+import { mkdir as mkdir4, writeFile } from "fs/promises";
 import { createRequire as createRequire2 } from "module";
-import { dirname as dirname4, join as join11, resolve as resolve8 } from "path";
+import { dirname as dirname6, join as join11, resolve as resolve10 } from "path";
 import { parseLessonkitInterchange } from "@lxpack/validators";
 function resolveLessonkitVersion(explicit) {
   if (explicit?.trim()) return explicit.trim();
@@ -2620,7 +2816,7 @@ function resolveLessonkitVersion(explicit) {
   }
 }
 async function exportLkcourse(options) {
-  const projectRoot = resolve8(options.projectRoot);
+  const projectRoot = resolve10(options.projectRoot);
   const manifest = options.manifest;
   const spaDistDir = join11(projectRoot, manifest.paths.spaDistDir);
   try {
@@ -2637,6 +2833,16 @@ async function exportLkcourse(options) {
       ]
     };
   }
+  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 = parseLessonkitInterchange(interchange);
   if (!interchangeParsed.ok) {
@@ -2728,10 +2934,11 @@ async function exportLkcourse(options) {
     return { ok: false, issues: envelopeCheck.issues };
   }
   zipEntries.set("manifest.json", utf8ToEntry(JSON.stringify(envelope, null, 2)));
-  const archivePath = resolve8(
+  const archivePath = resolve10(
     projectRoot,
     options.outPath ?? `${manifest.name}.lkcourse`
   );
+  const archiveRel = options.outPath ?? `${manifest.name}.lkcourse`;
   try {
     assertRealPathUnderRoot(projectRoot, archivePath);
   } catch (err) {
@@ -2739,20 +2946,31 @@ async function exportLkcourse(options) {
       ok: false,
       issues: [
         {
-          path: options.outPath ?? `${manifest.name}.lkcourse`,
+          path: archiveRel,
           message: err instanceof Error ? err.message : String(err)
         }
       ]
     };
   }
-  if (!isSafeZipEntryPath(options.outPath ?? `${manifest.name}.lkcourse`)) {
+  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 mkdir3(dirname4(archivePath), { recursive: true });
+    await mkdir4(dirname6(archivePath), { recursive: true });
     const zipped = createZip(zipEntries);
     await writeFile(archivePath, zipped);
   } catch (err) {
@@ -2776,6 +2994,29 @@ async function exportLkcourse(options) {
 
 // src/lkcourse/validate.ts
 import { parseLessonkitInterchange as parseLessonkitInterchange2 } from "@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");
@@ -2808,6 +3049,8 @@ function validateLkcourseArchiveEntries(entries, _archiveLabel) {
   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({
@@ -2816,6 +3059,16 @@ function validateLkcourseArchiveEntries(entries, _archiveLabel) {
       });
     }
   }
+  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 {
@@ -2849,6 +3102,12 @@ function validateLkcourseArchiveEntries(entries, _archiveLabel) {
       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) {
@@ -2888,8 +3147,8 @@ function validateLkcourse(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";
+import { access as access3, cp as cp2, mkdir as mkdir5, mkdtemp as mkdtemp3, readdir as readdir3, rename as rename2, rm as rm4, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname7, join as join12, resolve as resolve11 } from "path";
 var IMPORT_ARTIFACTS = ["lessonkit.json", "dist"];
 async function pathExists2(path) {
   try {
@@ -2910,7 +3169,7 @@ async function renameOrCopy2(from, to, opts) {
     await rm4(from, { recursive: true, force: true });
   }
 }
-async function writeImportTree(stagingDir, manifest, entries, spaDistDir) {
+async function writeImportTree(stagingDir, manifest, entries, spaDistDir, allowlistedSpaPaths) {
   let fileCount = 0;
   await writeFile2(
     join12(stagingDir, "lessonkit.json"),
@@ -2922,14 +3181,17 @@ async function writeImportTree(stagingDir, manifest, entries, spaDistDir) {
   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 = join12(stagingDir, spaDistDir, relativeUnderSpa);
-    const resolvedOut = resolve9(outPath);
+    const resolvedOut = resolve11(outPath);
     assertRealPathUnderRoot(stagingDir, resolvedOut);
     if (!isSafeZipEntryPath(join12(spaDistDir, relativeUnderSpa))) {
       throw new Error(`unsafe extraction path: ${entryPath}`);
     }
-    await mkdir4(dirname5(resolvedOut), { recursive: true });
+    await mkdir5(dirname7(resolvedOut), { recursive: true });
     await writeFile2(resolvedOut, data);
     fileCount += 1;
   }
@@ -2960,30 +3222,49 @@ async function restoreImportBackup(targetDir, backupDir) {
     await renameOrCopy2(backupPath, destPath);
   }
 }
+async function snapshotPreExistingImportArtifacts(targetDir) {
+  const existing = /* @__PURE__ */ new Set();
+  for (const name of IMPORT_ARTIFACTS) {
+    if (await pathExists2(join12(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 = join12(targetDir, name);
+    if (await pathExists2(destPath)) {
+      await rm4(destPath, { recursive: true, force: true });
+    }
+  }
+}
 async function promoteImportStaging(stagingDir, targetDir) {
+  await mkdir5(targetDir, { recursive: true });
   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);
+    if (entry.isDirectory() || entry.isFile()) {
+      await renameOrCopy2(srcPath, destPath);
     }
   }
 }
 var promoteImportStagingImpl = promoteImportStaging;
 async function importLkcourse(options) {
-  const archivePath = resolve9(options.archivePath);
-  const targetDir = resolve9(options.targetDir);
+  const archivePath = resolve11(options.archivePath);
+  const targetDir = resolve11(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 });
+    await mkdir5(targetDir, { recursive: true });
     assertRealPathUnderRoot(targetDir, targetDir);
   } catch (err) {
     return {
@@ -3000,16 +3281,26 @@ async function importLkcourse(options) {
   if (!read.ok) return read;
   let stagingDir;
   let backupDir;
+  let preExisting;
   try {
     stagingDir = await mkdtemp3(join12(targetDir, ".lkcourse-import-"));
-    const fileCount = await writeImportTree(stagingDir, manifest, read.entries, spaDistDir);
+    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) {
-      if (backupDir) {
-        await restoreImportBackup(targetDir, backupDir);
-      }
+      await rollbackFailedImport(targetDir, backupDir, preExisting);
+      backupDir = void 0;
       throw promoteError;
     }
     if (backupDir) {
@@ -3026,8 +3317,12 @@ async function importLkcourse(options) {
       fileCount
     };
   } catch (err) {
-    if (backupDir) {
+    if (preExisting) {
+      await rollbackFailedImport(targetDir, backupDir, preExisting).catch(() => void 0);
+    } else if (backupDir) {
       await restoreImportBackup(targetDir, backupDir).catch(() => void 0);
+    }
+    if (backupDir) {
       await rm4(backupDir, { recursive: true, force: true }).catch(() => void 0);
     }
     if (stagingDir) {
@@ -3078,6 +3373,7 @@ export {
   validateLessonkitProject,
   validateLkcourse,
   validateLkcourseArchiveEntries,
+  validateManifestName,
   validatePackageInputs,
   validateProjectPaths,
   validateReactManifestParity,