@lessonkit/lxpack 1.3.1 → 1.5.0

package/dist/index.cjs

@@ -36,6 +36,7 @@ __export(index_exports, {
   buildStagingPackage: () => buildStagingPackage,
   descriptorToInterchange: () => descriptorToInterchange,
   ensureOutDirParent: () => ensureOutDirParent,
+  escapeShellText: () => escapeShellText,
   extractAssessments: () => extractAssessments,
   lessonkitInterchangeSchema: () => import_validators2.lessonkitInterchangeSchema,
   loadLessonkitManifestFromFile: () => loadLessonkitManifestFromFile,
@@ -375,6 +376,10 @@ var validateMcqLike = (assessment, path, issues) => {
   } else if (trimmedChoices.length && !trimmedChoices.includes(assessment.answer.trim())) {
     issues.push({ path: `${path}.answer`, message: "answer must match a choice" });
   }
+  const uniqueChoices = new Set(trimmedChoices);
+  if (trimmedChoices.length !== uniqueChoices.size) {
+    issues.push({ path: `${path}.choices`, message: "choices must be unique" });
+  }
 };
 function countStarDelimitedBlanks(template) {
   const matches = template.match(/\*[^*]+\*/g);
@@ -400,8 +405,30 @@ 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 = assessment.blanks?.map((b) => ({ id: b.id?.trim() ?? "", answer: b.answer?.trim() ?? "" })).filter((b) => b.id.length > 0 && b.answer.length > 0) ?? [];
+    if (assessment.blanks !== void 0 && explicitBlanks.length === 0) {
+      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) => {
@@ -599,27 +626,47 @@ function validateCourseDescriptor(input) {
 }
 
 // src/assessments.ts
+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) || /</.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 choices = assessment.choices.map((text, index) => {
+    const sanitizedText = sanitizeShellField(text);
+    if (!sanitizedText) return null;
     const id = slugChoiceId(text, index);
     return {
       id,
-      text,
+      text: sanitizedText,
       correct: text === assessment.answer
     };
   });
+  if (choices.some((choice) => choice === null)) return null;
   return {
-    id: assessment.checkId,
+    id: checkId,
     passingScore: assessment.passingScore ?? 1,
     questions: [
       {
         id: "q1",
-        prompt: assessment.question,
+        prompt,
         choices
       }
     ]
@@ -642,15 +689,8 @@ function assessmentDescriptorToLxpack(assessment) {
   if (kind === "fillInBlanks") {
     return null;
   }
-  if (kind === "findHotspot" && assessment.kind === "findHotspot") {
-    return mcqToLxpack({
-      kind: "mcq",
-      checkId: assessment.checkId,
-      question: assessment.question,
-      choices: [assessment.correctTargetId, "other"],
-      answer: assessment.correctTargetId,
-      passingScore: assessment.passingScore
-    });
+  if (kind === "findHotspot") {
+    return null;
   }
   if (kind === "findMultipleHotspots") {
     return null;
@@ -664,6 +704,20 @@ function extractAssessments(descriptor) {
   return (descriptor.assessments ?? []).map(assessmentDescriptorToLxpack).filter((a) => a !== null);
 }
 
+// src/descriptor/validateInjectableAssessments.ts
+function validateInjectableAssessments(descriptor) {
+  const issues = [];
+  (descriptor.assessments ?? []).forEach((assessment, index) => {
+    if (assessmentDescriptorToLxpack(assessment) === null) {
+      issues.push({
+        path: `assessments[${index}]`,
+        message: `assessment kind "${assessment.kind ?? "mcq"}" (checkId "${assessment.checkId}") is not injected into LMS shell quizzes`
+      });
+    }
+  });
+  return issues;
+}
+
 // src/descriptor/validateForTarget.ts
 var LMS_SHELL_TARGETS = /* @__PURE__ */ new Set([
   "scorm12",
@@ -672,26 +726,34 @@ var LMS_SHELL_TARGETS = /* @__PURE__ */ new Set([
   "xapi",
   "cmi5"
 ]);
+function appendActivityIriIssues(issues, descriptor, target) {
+  const hasXapiTracking = Boolean(descriptor.tracking?.xapi);
+  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: "course.tracking.xapi.activityIri",
-        message: "tracking.xapi.activityIri is required for xapi and cmi5 export targets"
-      });
-    }
-  }
+  appendActivityIriIssues(issues, descriptor, target);
   if (LMS_SHELL_TARGETS.has(target)) {
-    (descriptor.assessments ?? []).forEach((assessment, index) => {
-      if (assessmentDescriptorToLxpack(assessment) === null) {
-        issues.push({
-          path: `assessments[${index}]`,
-          message: `assessment kind "${assessment.kind ?? "mcq"}" (checkId "${assessment.checkId}") is not injected into LMS shell quizzes for target "${target}"`
-        });
-      }
-    });
+    issues.push(...validateInjectableAssessments(descriptor).map((issue) => ({
+      ...issue,
+      message: `${issue.message} for target "${target}"`
+    })));
   }
   return issues;
 }
@@ -723,16 +785,50 @@ function validateDescriptorForTarget(input, target) {
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
 var SCANNABLE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
-function collectSourceUnderSrc(projectRoot) {
+function collectSourceUnderSrc(projectRoot, issues) {
   const srcDir = (0, import_node_path2.join)(projectRoot, "src");
   if (!(0, import_node_fs2.existsSync)(srcDir)) return [];
   const results = [];
   const walk = (dir) => {
     for (const entry of (0, import_node_fs2.readdirSync)(dir)) {
       const abs = (0, import_node_path2.join)(dir, entry);
-      if ((0, import_node_fs2.statSync)(abs).isDirectory()) {
+      let stat2;
+      try {
+        stat2 = (0, import_node_fs2.lstatSync)(abs);
+      } catch {
+        continue;
+      }
+      if (stat2.isSymbolicLink()) {
+        issues.push({
+          path: (0, import_node_path2.relative)(projectRoot, abs),
+          message: `Source tree contains symlink (rejected for parity scan): ${(0, import_node_path2.relative)(projectRoot, abs)}`,
+          severity: "error"
+        });
+        continue;
+      }
+      if (stat2.isDirectory()) {
+        try {
+          assertRealPathUnderRoot(projectRoot, abs);
+        } catch {
+          issues.push({
+            path: (0, import_node_path2.relative)(projectRoot, abs),
+            message: `Source directory escapes project root: ${(0, import_node_path2.relative)(projectRoot, abs)}`,
+            severity: "error"
+          });
+          continue;
+        }
         walk(abs);
       } else if (SCANNABLE_EXTENSIONS.some((ext) => entry.endsWith(ext))) {
+        try {
+          assertRealPathUnderRoot(projectRoot, abs);
+        } catch {
+          issues.push({
+            path: (0, import_node_path2.relative)(projectRoot, abs),
+            message: `Source file escapes project root: ${(0, import_node_path2.relative)(projectRoot, abs)}`,
+            severity: "error"
+          });
+          continue;
+        }
         results.push((0, import_node_path2.relative)(projectRoot, abs));
       }
     }
@@ -740,20 +836,69 @@ function collectSourceUnderSrc(projectRoot) {
   walk(srcDir);
   return results;
 }
-function readAppSources(projectRoot, appSources) {
-  return appSources.map((rel) => (0, import_node_path2.join)(projectRoot, rel)).filter((abs) => (0, import_node_fs2.existsSync)(abs)).map((abs) => (0, import_node_fs2.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 = (0, import_node_path2.join)(projectRoot, rel);
+    try {
+      assertRealPathUnderRoot(projectRoot, abs);
+      if ((0, import_node_fs2.existsSync)(abs) && (0, import_node_fs2.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 (!(0, import_node_fs2.existsSync)(abs)) return null;
+    return (0, import_node_fs2.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);
@@ -764,7 +909,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 = [
@@ -773,51 +920,93 @@ 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);
-  if (idPropPatterns("checkId", checkId).some((p) => stripped.includes(p))) return true;
-  return idUsedViaConstant(stripped, "checkId", checkId, extractStringConstants(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 courseIdPresent(source, courseId) {
+  if (idPropPresent(source, "courseId", courseId)) return true;
+  if (idUsedViaConstant(source, "courseId", courseId, extractStringConstants(source))) 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({
       path: "course.courseId",
-      message: `React app source does not reference courseId="${courseId}" from lessonkit.json`,
+      message: parityHint(
+        `React app source does not reference courseId="${courseId}" from lessonkit.json.`
+      ),
       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;
     if (!checkIdPresent(source, checkId)) {
       issues.push({
         path: `assessments.checkId:${checkId}`,
-        message: `React app source missing checkId="${checkId}" declared in lessonkit.json`,
+        message: parityHint(
+          `React app source missing checkId="${checkId}" declared in lessonkit.json.`
+        ),
         severity: "error"
       });
     }
@@ -827,7 +1016,13 @@ function validateReactManifestParity(opts) {
 
 // src/validateProjectPaths.ts
 var import_node_path3 = require("path");
-function validatePathField(value, fieldPath, projectRoot, issues) {
+var RESERVED_OUTPUT_SEGMENTS = /* @__PURE__ */ new Set([".git", "node_modules", ".github"]);
+function isReservedOutputPath(value) {
+  const normalized = value.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+  const segments = normalized.split("/").filter(Boolean);
+  return segments.some((segment) => RESERVED_OUTPUT_SEGMENTS.has(segment));
+}
+function validatePathField(value, fieldPath, projectRoot, issues, options) {
   if (!isSafeRelativeSpaPath(value)) {
     issues.push({
       path: fieldPath,
@@ -835,6 +1030,13 @@ function validatePathField(value, fieldPath, projectRoot, issues) {
     });
     return;
   }
+  if (options?.rejectReserved && isReservedOutputPath(value)) {
+    issues.push({
+      path: fieldPath,
+      message: "path must not target reserved directories (.git, node_modules, .github)"
+    });
+    return;
+  }
   try {
     assertRealPathUnderRoot(projectRoot, (0, import_node_path3.resolve)(projectRoot, value));
   } catch {
@@ -851,10 +1053,14 @@ function validateProjectPaths(projectRoot, paths) {
     validatePathField(paths.spaDistDir.trim(), "paths.spaDistDir", root, issues);
   }
   if (paths.lxpackOutDir?.trim()) {
-    validatePathField(paths.lxpackOutDir.trim(), "paths.lxpackOutDir", root, issues);
+    validatePathField(paths.lxpackOutDir.trim(), "paths.lxpackOutDir", root, issues, {
+      rejectReserved: true
+    });
   }
   if (paths.outputBaseDir?.trim()) {
-    validatePathField(paths.outputBaseDir.trim(), "paths.outputBaseDir", root, issues);
+    validatePathField(paths.outputBaseDir.trim(), "paths.outputBaseDir", root, issues, {
+      rejectReserved: true
+    });
   }
   return issues;
 }
@@ -867,11 +1073,17 @@ function resolveSafePackageOutputOverride(projectRoot, override) {
   if ((0, import_node_path3.isAbsolute)(trimmed)) {
     const resolved2 = (0, import_node_path3.resolve)(trimmed);
     assertRealPathUnderRoot(root, resolved2);
+    if (isReservedOutputPath(trimmed)) {
+      throw new Error(`unsafe output path: ${override} targets a reserved directory`);
+    }
     return resolved2;
   }
   if (!isSafeRelativeSpaPath(trimmed)) {
     throw new Error(`unsafe output path: ${override}`);
   }
+  if (isReservedOutputPath(trimmed)) {
+    throw new Error(`unsafe output path: ${override} targets a reserved directory`);
+  }
   const resolved = (0, import_node_path3.resolve)(root, trimmed);
   assertRealPathUnderRoot(root, resolved);
   return resolved;
@@ -948,7 +1160,7 @@ function descriptorToInterchange(descriptor) {
 }
 
 // src/writeProject.ts
-var import_node_path5 = require("path");
+var import_node_path6 = require("path");
 var import_validators = require("@lxpack/validators");
 
 // src/spaDirs.ts
@@ -1006,6 +1218,62 @@ async function resolveSpaDirs(options) {
   return dirs;
 }
 
+// src/spaDistValidation.ts
+var import_promises2 = require("fs/promises");
+var import_node_fs3 = require("fs");
+var import_node_path5 = require("path");
+async function assertSpaDistContentsSafe(spaDirs, projectRoot) {
+  for (const [label, dir] of Object.entries(spaDirs)) {
+    const dirResolved = resolveComparablePath(dir);
+    const dirStat = await (0, import_promises2.lstat)(dirResolved);
+    if (dirStat.isSymbolicLink()) {
+      throw new Error(`spa dist for "${label}" cannot be a symlink: ${dir}`);
+    }
+    let rootReal;
+    try {
+      rootReal = (0, import_node_fs3.realpathSync)(dirResolved);
+    } catch {
+      throw new Error(`spa dist for "${label}" is not readable: ${dir}`);
+    }
+    if (projectRoot) {
+      assertRealPathUnderRoot(projectRoot, dir);
+    }
+    assertResolvedPathUnderRoot(rootReal, rootReal);
+    await walkDistDir(rootReal, rootReal, label);
+  }
+}
+async function walkDistDir(rootReal, current, label) {
+  let entries;
+  try {
+    entries = await (0, import_promises2.readdir)(current, { withFileTypes: true });
+  } catch (err) {
+    throw new Error(
+      `spa dist for "${label}" is not readable: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err }
+    );
+  }
+  for (const entry of entries) {
+    const entryPath = (0, import_node_path5.join)(current, entry.name);
+    const stat2 = await (0, import_promises2.lstat)(entryPath);
+    if (stat2.isSymbolicLink()) {
+      throw new Error(`spa dist for "${label}" contains symlink: ${entryPath}`);
+    }
+    let entryReal;
+    try {
+      entryReal = (0, import_node_fs3.realpathSync)(entryPath);
+    } catch (err) {
+      throw new Error(
+        `spa dist for "${label}" could not resolve path: ${entryPath}`,
+        { cause: err }
+      );
+    }
+    assertResolvedPathUnderRoot(rootReal, entryReal);
+    if (stat2.isDirectory()) {
+      await walkDistDir(rootReal, entryPath, label);
+    }
+  }
+}
+
 // src/writeProject.ts
 async function writeLxpackProject(options) {
   const validation = validateDescriptor(options.descriptor);
@@ -1015,11 +1283,14 @@ async function writeLxpackProject(options) {
     );
   }
   const descriptor = validation.descriptor;
-  const outDir = (0, import_node_path5.resolve)(options.outDir);
-  if (options.projectRoot) {
-    assertRealPathUnderRoot((0, import_node_path5.resolve)(options.projectRoot), outDir);
+  const injectableIssues = validateInjectableAssessments(descriptor);
+  if (injectableIssues.length > 0) {
+    throw new Error(injectableIssues.map((i) => `${i.path}: ${i.message}`).join("; "));
   }
+  const outDir = (0, import_node_path6.resolve)(options.outDir);
+  assertRealPathUnderRoot((0, import_node_path6.resolve)(options.projectRoot), outDir);
   const spaDirs = await resolveSpaDirs({ ...options, descriptor });
+  await assertSpaDistContentsSafe(spaDirs, options.projectRoot);
   const interchange = descriptorToInterchange(descriptor);
   const materialized = await (0, import_validators.materializeLessonkitProject)({
     interchange,
@@ -1035,21 +1306,21 @@ async function writeLxpackProject(options) {
   const courseDir = materialized.courseDir;
   return {
     outDir: courseDir,
-    courseYamlPath: (0, import_node_path5.join)(courseDir, "course.yaml"),
-    lessonkitJsonPath: (0, import_node_path5.join)(courseDir, "lessonkit.json")
+    courseYamlPath: (0, import_node_path6.join)(courseDir, "course.yaml"),
+    lessonkitJsonPath: (0, import_node_path6.join)(courseDir, "lessonkit.json")
   };
 }
 
 // src/packageCourse.ts
-var import_node_path9 = require("path");
+var import_node_path10 = require("path");
 var fsp3 = __toESM(require("fs/promises"), 1);
 var import_api2 = require("@lxpack/api");
 
 // src/packaging/validateInputs.ts
-var import_node_path6 = require("path");
+var import_node_path7 = require("path");
 function validatePackageInputs(options) {
   const { target, output, outputBaseDir } = options;
-  const outDir = (0, import_node_path6.resolve)(options.outDir);
+  const outDir = (0, import_node_path7.resolve)(options.outDir);
   if (!options.projectRoot) {
     return {
       ok: false,
@@ -1058,7 +1329,7 @@ function validatePackageInputs(options) {
       issues: [{ path: "projectRoot", message: "projectRoot is required for packageLessonkitCourse" }]
     };
   }
-  const projectRoot = (0, import_node_path6.resolve)(options.projectRoot);
+  const projectRoot = (0, import_node_path7.resolve)(options.projectRoot);
   try {
     assertRealPathUnderRoot(projectRoot, outDir);
   } catch (err) {
@@ -1086,9 +1357,9 @@ function validatePackageInputs(options) {
     };
   }
   if (output && !isSafeRelativeSpaPath(output)) {
-    if ((0, import_node_path6.isAbsolute)(output)) {
+    if ((0, import_node_path7.isAbsolute)(output)) {
       try {
-        assertRealPathUnderRoot(projectRoot, (0, import_node_path6.resolve)(output));
+        assertRealPathUnderRoot(projectRoot, (0, import_node_path7.resolve)(output));
       } catch (err) {
         return {
           ok: false,
@@ -1115,7 +1386,7 @@ function validatePackageInputs(options) {
     }
   }
   if (outputBaseDir) {
-    const resolvedOutputBase = (0, import_node_path6.resolve)(projectRoot, outputBaseDir);
+    const resolvedOutputBase = (0, import_node_path7.resolve)(projectRoot, outputBaseDir);
     try {
       assertRealPathUnderRoot(projectRoot, resolvedOutputBase);
     } catch (err) {
@@ -1136,7 +1407,7 @@ function validatePackageInputs(options) {
     }
   }
   if (output) {
-    const resolvedOutput = (0, import_node_path6.isAbsolute)(output) ? (0, import_node_path6.resolve)(output) : (0, import_node_path6.resolve)(projectRoot, output);
+    const resolvedOutput = (0, import_node_path7.isAbsolute)(output) ? (0, import_node_path7.resolve)(output) : (0, import_node_path7.resolve)(projectRoot, output);
     try {
       assertRealPathUnderRoot(projectRoot, resolvedOutput);
     } catch (err) {
@@ -1176,20 +1447,20 @@ function remapArtifactPaths(stagingRoot, outDir, artifactPath) {
     throw new Error(`${artifactPath} is outside the staging directory`);
   }
   const rel = relativePathUnderRoot(stagingRoot, resolved);
-  if (rel.startsWith("..") || (0, import_node_path6.isAbsolute)(rel)) {
+  if (rel.startsWith("..") || (0, import_node_path7.isAbsolute)(rel)) {
     throw new Error(`${artifactPath} is outside the staging directory`);
   }
   if (!rel) return outDir;
   if (/^[a-zA-Z]:[/\\]/.test(outDir)) {
-    return import_node_path6.win32.join(outDir, rel.replace(/\//g, import_node_path6.win32.sep));
+    return import_node_path7.win32.join(outDir, rel.replace(/\//g, import_node_path7.win32.sep));
   }
-  return (0, import_node_path6.join)(outDir, rel);
+  return (0, import_node_path7.join)(outDir, rel);
 }
 
 // src/packaging/promote.ts
 var fsp = __toESM(require("fs/promises"), 1);
 var import_node_crypto = require("crypto");
-var import_node_path7 = require("path");
+var import_node_path8 = require("path");
 async function pathExists(path) {
   try {
     await fsp.access(path);
@@ -1209,37 +1480,54 @@ async function renameOrCopy(from, to) {
   }
 }
 function promoteLockPath(outDir) {
-  const parent = (0, import_node_path7.dirname)(outDir);
-  const hash = (0, import_node_crypto.createHash)("sha256").update((0, import_node_path7.resolve)(outDir)).digest("hex").slice(0, 16);
-  return (0, import_node_path7.join)(parent, `.lk-promote-lock-${hash}`);
+  const parent = (0, import_node_path8.dirname)(outDir);
+  const hash = (0, import_node_crypto.createHash)("sha256").update((0, import_node_path8.resolve)(outDir)).digest("hex").slice(0, 16);
+  return (0, import_node_path8.join)(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;
   }
 }
 async function withPromoteLock(outDir, fn) {
   const lockPath = promoteLockPath(outDir);
-  await fsp.mkdir((0, import_node_path7.dirname)(outDir), { recursive: true });
+  await fsp.mkdir((0, import_node_path8.dirname)(outDir), { recursive: true });
   let lockHandle;
   for (let attempt = 0; attempt < 200; attempt++) {
     try {
       lockHandle = await fsp.open(lockPath, "wx");
       await lockHandle.writeFile(`${process.pid}
+${(0, import_node_crypto.randomUUID)()}
+${Date.now()}
 `, "utf8");
       break;
     } catch (err) {
@@ -1271,26 +1559,81 @@ 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 = (0, import_node_path8.join)(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 = (0, import_node_path8.join)(priorArtifactsDir, rel);
+    const dest = (0, import_node_path8.join)(destArtifactsDir, rel);
+    await fsp.mkdir((0, import_node_path8.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((0, import_node_path8.resolve)(options.projectRoot), (0, import_node_path8.resolve)(outDir));
+  }
   return withPromoteLock(outDir, async () => {
-    await assertNoLegacyPromoteArtifacts(outDir);
-    const parent = (0, import_node_path7.dirname)(outDir);
-    const tmpPromote = await fsp.mkdtemp((0, import_node_path7.join)(parent, ".lk-promote-"));
+    await removeStaleLegacyPromoteArtifacts(outDir);
+    const stagingArtifactsDir = (0, import_node_path8.join)(stagingDir, outputBaseDir);
+    const newArtifactPaths = /* @__PURE__ */ new Set();
+    if (await pathExists(stagingArtifactsDir)) {
+      for (const rel of await listRelativePaths(stagingArtifactsDir)) {
+        newArtifactPaths.add(rel);
+      }
+    }
+    const parent = (0, import_node_path8.dirname)(outDir);
+    let priorArtifactsBackup;
+    const existingArtifactsDir = (0, import_node_path8.join)(outDir, outputBaseDir);
+    if (await pathExists(outDir) && await pathExists(existingArtifactsDir)) {
+      priorArtifactsBackup = await fsp.mkdtemp((0, import_node_path8.join)(parent, ".lk-prior-out-"));
+      await fsp.cp(existingArtifactsDir, (0, import_node_path8.join)(priorArtifactsBackup, outputBaseDir), { recursive: true });
+    }
+    const tmpPromote = await fsp.mkdtemp((0, import_node_path8.join)(parent, ".lk-promote-"));
     await renameOrCopy(stagingDir, tmpPromote);
     const hadOutDir = await pathExists(outDir);
-    const backup = hadOutDir ? await fsp.mkdtemp((0, import_node_path7.join)(parent, ".lk-backup-")) : void 0;
+    const backup = hadOutDir ? await fsp.mkdtemp((0, import_node_path8.join)(parent, ".lk-backup-")) : void 0;
     if (hadOutDir && backup) {
       await renameOrCopy(outDir, backup);
     }
@@ -1301,7 +1644,7 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
         try {
           await renameOrCopy(backup, outDir);
         } catch (restoreError) {
-          const failedPromote2 = (0, import_node_path7.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
+          const failedPromote2 = (0, import_node_path8.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
           try {
             await renameOrCopy(tmpPromote, failedPromote2);
           } catch {
@@ -1313,7 +1656,8 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
           const promoteMsg = promoteError instanceof Error ? promoteError.message : String(promoteError);
           const restoreMsg = restoreError instanceof Error ? restoreError.message : String(restoreError);
           throw new Error(
-            `[lessonkit/lxpack] promote failed (${promoteMsg}) and could not restore ${outDir} (${restoreMsg}). Recovery: previous output may be in ${backup}; staged package may be in ${failedPromote2}.`
+            `[lessonkit/lxpack] promote failed (${promoteMsg}) and could not restore ${outDir} (${restoreMsg}). Recovery: previous output may be in ${backup}; staged package may be in ${failedPromote2}.`,
+            { cause: restoreError }
           );
         }
       } else {
@@ -1331,7 +1675,7 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
         }
         throw promoteError;
       }
-      const failedPromote = (0, import_node_path7.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
+      const failedPromote = (0, import_node_path8.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
       try {
         await renameOrCopy(tmpPromote, failedPromote);
       } catch {
@@ -1342,6 +1686,20 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
       }
       throw promoteError;
     }
+    if (priorArtifactsBackup) {
+      try {
+        await mergePreservedOutArtifacts(
+          (0, import_node_path8.join)(priorArtifactsBackup, outputBaseDir),
+          (0, import_node_path8.join)(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 */
@@ -1353,16 +1711,18 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
 
 // src/packaging/staging.ts
 var fsp2 = __toESM(require("fs/promises"), 1);
-var import_node_path8 = require("path");
+var import_node_path9 = require("path");
 var import_node_os = require("os");
 var import_api = require("@lxpack/api");
 async function buildStagingPackage(options) {
   const { target, output, dir, outputBaseDir, descriptor, ...writeOpts } = options;
-  const stagingDir = await fsp2.mkdtemp((0, import_node_path8.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
+  const stagingDir = await fsp2.mkdtemp((0, import_node_path9.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
+  let succeeded = false;
   try {
     let spaDirs;
     try {
       spaDirs = await resolveSpaDirs({ ...writeOpts, descriptor });
+      await assertSpaDistContentsSafe(spaDirs, writeOpts.projectRoot);
     } catch (err) {
       return {
         ok: false,
@@ -1375,10 +1735,21 @@ async function buildStagingPackage(options) {
         ]
       };
     }
+    const injectableIssues = validateInjectableAssessments(descriptor);
+    if (injectableIssues.length > 0) {
+      return {
+        ok: false,
+        stagingDir,
+        issues: injectableIssues.map((i) => ({
+          path: i.path,
+          message: i.message
+        }))
+      };
+    }
     const interchange = descriptorToInterchange(descriptor);
     const outputBase = outputBaseDir ?? ".lxpack/out";
-    await fsp2.mkdir((0, import_node_path8.join)(stagingDir, outputBase), { recursive: true });
-    const defaultOutput = output ?? (dir ? (0, import_node_path8.join)(outputBase, target) : (0, import_node_path8.join)(outputBase, `course-${target}.zip`));
+    await fsp2.mkdir((0, import_node_path9.join)(stagingDir, outputBase), { recursive: true });
+    const defaultOutput = output ?? (dir ? (0, import_node_path9.join)(outputBase, target) : (0, import_node_path9.join)(outputBase, `course-${target}.zip`));
     const build = await (0, import_api.packageLessonkit)({
       interchange,
       spaDirs,
@@ -1402,6 +1773,7 @@ async function buildStagingPackage(options) {
         }))
       };
     }
+    succeeded = true;
     return {
       ok: true,
       stagingDir,
@@ -1415,10 +1787,17 @@ 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) {
-  await fsp2.mkdir((0, import_node_path8.dirname)(outDir), { recursive: true });
+  await fsp2.mkdir((0, import_node_path9.dirname)(outDir), { recursive: true });
 }
 
 // src/packaging/issueSeverity.ts
@@ -1433,13 +1812,13 @@ function findPackagingErrorIssues(issues) {
 // src/packageCourse.ts
 async function validateLessonkitProject(options) {
   return (0, import_api2.validateCourse)({
-    courseDir: (0, import_node_path9.resolve)(options.courseDir),
+    courseDir: (0, import_node_path10.resolve)(options.courseDir),
     target: options.target
   });
 }
 async function buildLessonkitProject(options) {
   const buildOptions = {
-    courseDir: (0, import_node_path9.resolve)(options.courseDir),
+    courseDir: (0, import_node_path10.resolve)(options.courseDir),
     target: options.target,
     output: options.output,
     dir: options.dir,
@@ -1470,7 +1849,7 @@ async function packageLessonkitCourse(options) {
   if (!descriptorValidation.ok) {
     return {
       ok: false,
-      courseDir: (0, import_node_path9.resolve)(writeOpts.outDir),
+      courseDir: (0, import_node_path10.resolve)(writeOpts.outDir),
       target,
       issues: descriptorValidation.issues.map((i) => ({
         path: i.path,
@@ -1479,34 +1858,20 @@ async function packageLessonkitCourse(options) {
     };
   }
   const descriptor = descriptorValidation.descriptor;
-  if (writeOpts.projectRoot) {
-    const parityIssues = validateReactManifestParity({
-      projectRoot: writeOpts.projectRoot,
-      descriptor
-    });
-    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
-        }))
-      };
-    }
-  }
-  const nonInjectableAssessments = (descriptor.assessments ?? []).map((assessment, index) => ({ assessment, index })).filter(({ assessment }) => assessmentDescriptorToLxpack(assessment) === null);
-  if (nonInjectableAssessments.length > 0) {
+  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: nonInjectableAssessments.map(({ assessment, index }) => ({
-        path: `assessments[${index}]`,
-        message: `assessment kind "${assessment.kind ?? "mcq"}" (checkId "${assessment.checkId}") is not injected into LMS shell quizzes for target "${target}"`
+      issues: parityFailures.map((i) => ({
+        path: i.path,
+        message: i.message,
+        severity: i.severity
       }))
     };
   }
@@ -1567,7 +1932,7 @@ 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
     };
@@ -1581,7 +1946,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 */
@@ -1704,6 +2072,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 ((key === "lxpackOutDir" || key === "outputBaseDir") && 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) {
@@ -1735,37 +2117,56 @@ var import_tracking_schema2 = require("@lxpack/tracking-schema");
 
 // src/telemetry.ts
 var import_tracking_schema = require("@lxpack/tracking-schema");
-var SUPPORTED = new Set(import_tracking_schema.LESSONKIT_TELEMETRY_EVENTS);
+var BRANCH_TELEMETRY_EVENTS = ["branch_node_viewed", "branch_selected"];
+var ASSESSMENT_TELEMETRY_EVENTS = ["assessment_answered"];
+var SUPPORTED = /* @__PURE__ */ new Set([
+  ...import_tracking_schema.LESSONKIT_TELEMETRY_EVENTS,
+  ...BRANCH_TELEMETRY_EVENTS,
+  ...ASSESSMENT_TELEMETRY_EVENTS
+]);
 function isQuizAnsweredData(data) {
-  return typeof data === "object" && data !== null && typeof data.checkId === "string";
+  return typeof data === "object" && data !== null && typeof data.checkId === "string" && data.checkId.length > 0;
 }
 function isQuizCompletedData(data) {
-  return typeof data === "object" && data !== null && typeof data.checkId === "string";
+  return typeof data === "object" && data !== null && typeof data.checkId === "string" && data.checkId.length > 0;
+}
+function isAssessmentAnsweredData(data) {
+  return typeof data === "object" && data !== null && typeof data.checkId === "string" && data.checkId.length > 0;
 }
 function isInteractionData(data) {
   return typeof data === "object" && data !== null;
 }
+function isBranchNodeViewedData(data) {
+  return typeof data === "object" && data !== null && typeof data.blockId === "string" && typeof data.nodeId === "string";
+}
+function isBranchSelectedData(data) {
+  return typeof data === "object" && data !== null && typeof data.blockId === "string" && typeof data.fromNodeId === "string" && typeof data.toNodeId === "string";
+}
 function telemetryEventToLessonkit(event) {
   if (!SUPPORTED.has(event.name)) {
     return null;
   }
-  const name = event.name;
   const mapped = {
-    name,
+    name: event.name,
     lessonId: event.lessonId
   };
-  if (name === "quiz_completed" || name === "quiz_answered") {
+  if (event.name === "quiz_completed" || event.name === "quiz_answered" || event.name === "assessment_answered") {
     const data = event.data;
-    if (isQuizAnsweredData(data) || isQuizCompletedData(data)) {
-      mapped.assessmentId = data.checkId;
-      if ("score" in data) {
-        mapped.score = data.score;
-        mapped.maxScore = data.maxScore;
-        mapped.passingScore = data.passingScore;
-      }
-      mapped.data = data;
+    if (!isQuizAnsweredData(data) && !isQuizCompletedData(data) && !isAssessmentAnsweredData(data)) {
+      return null;
     }
-  } else if (name === "interaction" && event.data && isInteractionData(event.data)) {
+    mapped.assessmentId = data.checkId;
+    if ("score" in data) {
+      mapped.score = data.score;
+      mapped.maxScore = data.maxScore;
+      mapped.passingScore = data.passingScore;
+    }
+    mapped.data = data;
+  } else if (mapped.name === "interaction" && event.data && isInteractionData(event.data)) {
+    mapped.data = event.data;
+  } else if (event.name === "branch_node_viewed" && isBranchNodeViewedData(event.data)) {
+    mapped.data = event.data;
+  } else if (event.name === "branch_selected" && isBranchSelectedData(event.data)) {
     mapped.data = event.data;
   }
   return mapped;
@@ -1781,6 +2182,7 @@ var import_validators2 = require("@lxpack/validators");
   buildStagingPackage,
   descriptorToInterchange,
   ensureOutDirParent,
+  escapeShellText,
   extractAssessments,
   lessonkitInterchangeSchema,
   loadLessonkitManifestFromFile,