@lessonkit/lxpack 1.3.0 → 1.4.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-import { CheckId, CourseId, LessonId } from '@lessonkit/core';
+import { McqAssessmentProps, CheckId, CourseId, LessonId } from '@lessonkit/core';
+export { LmsBridgeMode, McqAssessmentProps } from '@lessonkit/core';
 import { ThemePresetName, LessonkitThemeV1 } from '@lessonkit/themes';
 import { ExportTarget, BuildCourseResult, ValidateCourseResult } from '@lxpack/api';
 export { ExportTarget } from '@lxpack/api';
@@ -14,14 +15,8 @@ type LessonDescriptor = {
     /** Built SPA folder relative to the LXPack project root (`per-lesson-spa` only). */
     spaPath?: string;
 };
-type McqAssessmentDescriptor = {
-    kind?: "mcq";
-    checkId: CheckId;
-    question: string;
-    choices: string[];
-    answer: string;
-    passingScore?: number;
-};
+/** @deprecated Use `McqAssessmentProps` from `@lessonkit/core`. */
+type McqAssessmentDescriptor = McqAssessmentProps;
 type TrueFalseAssessmentDescriptor = {
     kind: "trueFalse";
     checkId: CheckId;
@@ -110,6 +105,23 @@ type DescriptorValidationResult = {
 declare function validateDescriptor(input: unknown): DescriptorValidationResult;
 declare function validateDescriptorForTarget(input: unknown, target?: ExportTarget): DescriptorValidationResult;
 
+type ReactParityIssue = {
+    path: string;
+    message: string;
+    severity: "error" | "warning";
+};
+type ValidateReactManifestParityOptions = {
+    projectRoot: string;
+    descriptor: LessonkitCourseDescriptor;
+    /** Relative source files to scan (default: all `.tsx` under `src/`). */
+    appSources?: string[];
+};
+/**
+ * Validates that React app source references the same courseId and assessment checkIds
+ * as the lessonkit.json descriptor (prevents LMS/runtime ID drift at package time).
+ */
+declare function validateReactManifestParity(opts: ValidateReactManifestParityOptions): ReactParityIssue[];
+
 type ProjectPathsInput = {
     spaDistDir?: string;
     lxpackOutDir?: string;
@@ -218,6 +230,8 @@ type BuildStagingPackageResult = {
 declare function buildStagingPackage(options: BuildStagingPackageOptions): Promise<BuildStagingPackageResult>;
 declare function ensureOutDirParent(outDir: string): Promise<void>;
 
+/** LessonKit-owned alias for LMS export targets (maps to `@lxpack/api` `ExportTarget`). */
+type LessonkitExportTarget = ExportTarget;
 type ValidateLessonkitProjectOptions = {
     courseDir: string;
     target?: ExportTarget;
@@ -308,4 +322,4 @@ type ParseManifestResult = {
 declare function parseLessonkitManifest(raw: unknown, label?: string, projectRoot?: string): ParseManifestResult;
 declare function loadLessonkitManifestFromFile(readJson: () => Promise<unknown>, label?: string, projectRoot?: string): Promise<ParseManifestResult>;
 
-export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type FillInBlanksAssessmentDescriptor, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type McqAssessmentDescriptor, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type SpaLayout, type SpaLessonEntry, type TrueFalseAssessmentDescriptor, type ValidateLessonkitProjectOptions, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, writeLxpackProject };
+export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type FillInBlanksAssessmentDescriptor, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitExportTarget, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type McqAssessmentDescriptor, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type ReactParityIssue, type SpaLayout, type SpaLessonEntry, type TrueFalseAssessmentDescriptor, type ValidateLessonkitProjectOptions, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { CheckId, CourseId, LessonId } from '@lessonkit/core';
+import { McqAssessmentProps, CheckId, CourseId, LessonId } from '@lessonkit/core';
+export { LmsBridgeMode, McqAssessmentProps } from '@lessonkit/core';
 import { ThemePresetName, LessonkitThemeV1 } from '@lessonkit/themes';
 import { ExportTarget, BuildCourseResult, ValidateCourseResult } from '@lxpack/api';
 export { ExportTarget } from '@lxpack/api';
@@ -14,14 +15,8 @@ type LessonDescriptor = {
     /** Built SPA folder relative to the LXPack project root (`per-lesson-spa` only). */
     spaPath?: string;
 };
-type McqAssessmentDescriptor = {
-    kind?: "mcq";
-    checkId: CheckId;
-    question: string;
-    choices: string[];
-    answer: string;
-    passingScore?: number;
-};
+/** @deprecated Use `McqAssessmentProps` from `@lessonkit/core`. */
+type McqAssessmentDescriptor = McqAssessmentProps;
 type TrueFalseAssessmentDescriptor = {
     kind: "trueFalse";
     checkId: CheckId;
@@ -110,6 +105,23 @@ type DescriptorValidationResult = {
 declare function validateDescriptor(input: unknown): DescriptorValidationResult;
 declare function validateDescriptorForTarget(input: unknown, target?: ExportTarget): DescriptorValidationResult;
 
+type ReactParityIssue = {
+    path: string;
+    message: string;
+    severity: "error" | "warning";
+};
+type ValidateReactManifestParityOptions = {
+    projectRoot: string;
+    descriptor: LessonkitCourseDescriptor;
+    /** Relative source files to scan (default: all `.tsx` under `src/`). */
+    appSources?: string[];
+};
+/**
+ * Validates that React app source references the same courseId and assessment checkIds
+ * as the lessonkit.json descriptor (prevents LMS/runtime ID drift at package time).
+ */
+declare function validateReactManifestParity(opts: ValidateReactManifestParityOptions): ReactParityIssue[];
+
 type ProjectPathsInput = {
     spaDistDir?: string;
     lxpackOutDir?: string;
@@ -218,6 +230,8 @@ type BuildStagingPackageResult = {
 declare function buildStagingPackage(options: BuildStagingPackageOptions): Promise<BuildStagingPackageResult>;
 declare function ensureOutDirParent(outDir: string): Promise<void>;
 
+/** LessonKit-owned alias for LMS export targets (maps to `@lxpack/api` `ExportTarget`). */
+type LessonkitExportTarget = ExportTarget;
 type ValidateLessonkitProjectOptions = {
     courseDir: string;
     target?: ExportTarget;
@@ -308,4 +322,4 @@ type ParseManifestResult = {
 declare function parseLessonkitManifest(raw: unknown, label?: string, projectRoot?: string): ParseManifestResult;
 declare function loadLessonkitManifestFromFile(readJson: () => Promise<unknown>, label?: string, projectRoot?: string): Promise<ParseManifestResult>;
 
-export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type FillInBlanksAssessmentDescriptor, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type McqAssessmentDescriptor, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type SpaLayout, type SpaLessonEntry, type TrueFalseAssessmentDescriptor, type ValidateLessonkitProjectOptions, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, writeLxpackProject };
+export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type FillInBlanksAssessmentDescriptor, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitExportTarget, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type McqAssessmentDescriptor, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type ReactParityIssue, type SpaLayout, type SpaLessonEntry, type TrueFalseAssessmentDescriptor, type ValidateLessonkitProjectOptions, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };

package/dist/index.js

@@ -315,6 +315,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);
@@ -582,15 +586,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;
@@ -604,6 +601,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",
@@ -618,20 +629,21 @@ function validateDescriptorForExportTarget(descriptor, target) {
     const activityIri = descriptor.tracking?.xapi?.activityIri?.trim();
     if (!activityIri) {
       issues.push({
-        path: "course.tracking.xapi.activityIri",
+        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"
+      });
     }
   }
   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;
 }
@@ -659,6 +671,120 @@ function validateDescriptorForTarget(input, target) {
   return result;
 }
 
+// src/validateReactParity.ts
+import { readFileSync, existsSync as existsSync2, readdirSync, statSync } from "fs";
+import { join as join2, relative as relative2 } from "path";
+var SCANNABLE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
+function collectSourceUnderSrc(projectRoot) {
+  const srcDir = join2(projectRoot, "src");
+  if (!existsSync2(srcDir)) return [];
+  const results = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      const abs = join2(dir, entry);
+      if (statSync(abs).isDirectory()) {
+        walk(abs);
+      } else if (SCANNABLE_EXTENSIONS.some((ext) => entry.endsWith(ext))) {
+        results.push(relative2(projectRoot, abs));
+      }
+    }
+  };
+  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 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 extractStringConstants(source) {
+  const stripped = stripComments(source);
+  const map = /* @__PURE__ */ new Map();
+  const re = /(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(["'`])((?:\\.|(?!\2).)*)\2/g;
+  for (const match of stripped.matchAll(re)) {
+    map.set(match[1], match[3]);
+  }
+  return map;
+}
+function idUsedViaConstant(stripped, prop, id, constants) {
+  for (const [name, value] of constants) {
+    if (value !== id) continue;
+    const jsxPatterns = [
+      `${prop}={${name}}`,
+      `${prop}={ ${name} }`,
+      `${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;
+  }
+  return false;
+}
+function courseIdPresent(source, courseId) {
+  const stripped = stripComments(source);
+  if (idPropPatterns("courseId", courseId).some((p) => stripped.includes(p))) return true;
+  return idUsedViaConstant(stripped, "courseId", courseId, extractStringConstants(source));
+}
+function checkIdPresent(source, checkId) {
+  const stripped = stripComments(source);
+  if (idPropPatterns("checkId", checkId).some((p) => stripped.includes(p))) return true;
+  return idUsedViaConstant(stripped, "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 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"
+      }
+    ];
+  }
+  const issues = [];
+  const courseId = opts.descriptor.courseId;
+  if (!courseIdPresent(source, courseId)) {
+    issues.push({
+      path: "course.courseId",
+      message: parityHint(
+        `React app source does not reference courseId="${courseId}" from 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: parityHint(
+          `React app source missing checkId="${checkId}" declared in lessonkit.json.`
+        ),
+        severity: "error"
+      });
+    }
+  }
+  return issues;
+}
+
 // src/validateProjectPaths.ts
 import { isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
 function validatePathField(value, fieldPath, projectRoot, issues) {
@@ -782,12 +908,12 @@ function descriptorToInterchange(descriptor) {
 }
 
 // src/writeProject.ts
-import { join as join3, resolve as resolve4 } from "path";
+import { join as join5, resolve as resolve4 } from "path";
 import { materializeLessonkitProject } from "@lxpack/validators";
 
 // src/spaDirs.ts
 import { access } from "fs/promises";
-import { join as join2, resolve as resolve3 } from "path";
+import { join as join3, resolve as resolve3 } from "path";
 async function resolveSpaDirs(options) {
   const { descriptor, spaDistDir, lessonSpaDirs, projectRoot } = options;
   const spaLessons = resolveSpaLessons(descriptor);
@@ -804,9 +930,9 @@ async function resolveSpaDirs(options) {
       throw new Error(`spaDistDir not found: ${srcDist}`);
     }
     try {
-      await access(join2(srcDist, "index.html"));
+      await access(join3(srcDist, "index.html"));
     } catch {
-      throw new Error(`spaDistDir must contain index.html: ${join2(srcDist, "index.html")}`);
+      throw new Error(`spaDistDir must contain index.html: ${join3(srcDist, "index.html")}`);
     }
     const lessonId = spaLessons[0]?.id ?? /* v8 ignore next */
     "main";
@@ -829,10 +955,10 @@ async function resolveSpaDirs(options) {
       throw new Error(`lessonSpaDirs path not found for lesson "${lesson.id}": ${resolved}`);
     }
     try {
-      await access(join2(resolved, "index.html"));
+      await access(join3(resolved, "index.html"));
     } catch {
       throw new Error(
-        `lessonSpaDirs must contain index.html for lesson "${lesson.id}": ${join2(resolved, "index.html")}`
+        `lessonSpaDirs must contain index.html for lesson "${lesson.id}": ${join3(resolved, "index.html")}`
       );
     }
     dirs[lesson.id] = resolved;
@@ -840,6 +966,59 @@ async function resolveSpaDirs(options) {
   return dirs;
 }
 
+// src/spaDistValidation.ts
+import { lstat, readdir } from "fs/promises";
+import { realpathSync as realpathSync2 } from "fs";
+import { join as join4 } from "path";
+async function assertSpaDistContentsSafe(spaDirs, projectRoot) {
+  for (const [label, dir] of Object.entries(spaDirs)) {
+    const dirResolved = resolveComparablePath(dir);
+    const dirStat = await lstat(dirResolved);
+    if (dirStat.isSymbolicLink()) {
+      throw new Error(`spa dist for "${label}" cannot be a symlink: ${dir}`);
+    }
+    let rootReal;
+    try {
+      rootReal = realpathSync2(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 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 = join4(current, entry.name);
+    const stat2 = await lstat(entryPath);
+    if (stat2.isSymbolicLink()) {
+      throw new Error(`spa dist for "${label}" contains symlink: ${entryPath}`);
+    }
+    let entryReal;
+    try {
+      entryReal = realpathSync2(entryPath);
+    } catch {
+      entryReal = entryPath;
+    }
+    assertResolvedPathUnderRoot(rootReal, entryReal);
+    if (stat2.isDirectory()) {
+      await walkDistDir(rootReal, entryPath, label);
+    }
+  }
+}
+
 // src/writeProject.ts
 async function writeLxpackProject(options) {
   const validation = validateDescriptor(options.descriptor);
@@ -849,11 +1028,16 @@ 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("; "));
+  }
   const outDir = resolve4(options.outDir);
   if (options.projectRoot) {
     assertRealPathUnderRoot(resolve4(options.projectRoot), outDir);
   }
   const spaDirs = await resolveSpaDirs({ ...options, descriptor });
+  await assertSpaDistContentsSafe(spaDirs, options.projectRoot);
   const interchange = descriptorToInterchange(descriptor);
   const materialized = await materializeLessonkitProject({
     interchange,
@@ -869,8 +1053,8 @@ async function writeLxpackProject(options) {
   const courseDir = materialized.courseDir;
   return {
     outDir: courseDir,
-    courseYamlPath: join3(courseDir, "course.yaml"),
-    lessonkitJsonPath: join3(courseDir, "lessonkit.json")
+    courseYamlPath: join5(courseDir, "course.yaml"),
+    lessonkitJsonPath: join5(courseDir, "lessonkit.json")
   };
 }
 
@@ -883,7 +1067,7 @@ import {
 } from "@lxpack/api";
 
 // src/packaging/validateInputs.ts
-import { isAbsolute as isAbsolute3, join as join4, resolve as resolve5, win32 as win322 } from "path";
+import { isAbsolute as isAbsolute3, join as join6, resolve as resolve5, win32 as win322 } from "path";
 function validatePackageInputs(options) {
   const { target, output, outputBaseDir } = options;
   const outDir = resolve5(options.outDir);
@@ -1020,13 +1204,13 @@ function remapArtifactPaths(stagingRoot, outDir, artifactPath) {
   if (/^[a-zA-Z]:[/\\]/.test(outDir)) {
     return win322.join(outDir, rel.replace(/\//g, win322.sep));
   }
-  return join4(outDir, rel);
+  return join6(outDir, rel);
 }
 
 // src/packaging/promote.ts
 import * as fsp from "fs/promises";
 import { createHash, randomUUID } from "crypto";
-import { dirname, join as join5, resolve as resolve6 } from "path";
+import { dirname, join as join7, resolve as resolve6 } from "path";
 async function pathExists(path) {
   try {
     await fsp.access(path);
@@ -1048,22 +1232,23 @@ async function renameOrCopy(from, to) {
 function promoteLockPath(outDir) {
   const parent = dirname(outDir);
   const hash = createHash("sha256").update(resolve6(outDir)).digest("hex").slice(0, 16);
-  return join5(parent, `.lk-promote-lock-${hash}`);
+  return join7(parent, `.lk-promote-lock-${hash}`);
 }
 var STALE_LOCK_TTL_MS = 5 * 60 * 1e3;
 async function isStalePromoteLock(lockPath) {
   try {
-    const stat2 = await fsp.stat(lockPath);
-    if (Date.now() - stat2.mtimeMs > STALE_LOCK_TTL_MS) return true;
     const content = await fsp.readFile(lockPath, "utf8");
     const pid = Number.parseInt(content.trim(), 10);
-    if (!Number.isFinite(pid) || pid <= 0) return true;
-    try {
-      process.kill(pid, 0);
-      return false;
-    } catch {
-      return true;
+    if (Number.isFinite(pid) && pid > 0) {
+      try {
+        process.kill(pid, 0);
+        return false;
+      } catch {
+        return true;
+      }
     }
+    const stat2 = await fsp.stat(lockPath);
+    return Date.now() - stat2.mtimeMs > STALE_LOCK_TTL_MS;
   } catch {
     return true;
   }
@@ -1123,10 +1308,10 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
   return withPromoteLock(outDir, async () => {
     await assertNoLegacyPromoteArtifacts(outDir);
     const parent = dirname(outDir);
-    const tmpPromote = await fsp.mkdtemp(join5(parent, ".lk-promote-"));
+    const tmpPromote = await fsp.mkdtemp(join7(parent, ".lk-promote-"));
     await renameOrCopy(stagingDir, tmpPromote);
     const hadOutDir = await pathExists(outDir);
-    const backup = hadOutDir ? await fsp.mkdtemp(join5(parent, ".lk-backup-")) : void 0;
+    const backup = hadOutDir ? await fsp.mkdtemp(join7(parent, ".lk-backup-")) : void 0;
     if (hadOutDir && backup) {
       await renameOrCopy(outDir, backup);
     }
@@ -1137,7 +1322,7 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
         try {
           await renameOrCopy(backup, outDir);
         } catch (restoreError) {
-          const failedPromote2 = join5(parent, `.lk-failed-promote-${randomUUID()}`);
+          const failedPromote2 = join7(parent, `.lk-failed-promote-${randomUUID()}`);
           try {
             await renameOrCopy(tmpPromote, failedPromote2);
           } catch {
@@ -1149,7 +1334,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 {
@@ -1167,7 +1353,7 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
         }
         throw promoteError;
       }
-      const failedPromote = join5(parent, `.lk-failed-promote-${randomUUID()}`);
+      const failedPromote = join7(parent, `.lk-failed-promote-${randomUUID()}`);
       try {
         await renameOrCopy(tmpPromote, failedPromote);
       } catch {
@@ -1189,16 +1375,17 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
 
 // src/packaging/staging.ts
 import * as fsp2 from "fs/promises";
-import { dirname as dirname2, join as join6 } from "path";
+import { dirname as dirname2, join as join8 } 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(join6(tmpdir(), "lessonkit-lxpack-"));
+  const stagingDir = await fsp2.mkdtemp(join8(tmpdir(), "lessonkit-lxpack-"));
   try {
     let spaDirs;
     try {
       spaDirs = await resolveSpaDirs({ ...writeOpts, descriptor });
+      await assertSpaDistContentsSafe(spaDirs, writeOpts.projectRoot);
     } catch (err) {
       return {
         ok: false,
@@ -1211,10 +1398,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(join6(stagingDir, outputBase), { recursive: true });
-    const defaultOutput = output ?? (dir ? join6(outputBase, target) : join6(outputBase, `course-${target}.zip`));
+    await fsp2.mkdir(join8(stagingDir, outputBase), { recursive: true });
+    const defaultOutput = output ?? (dir ? join8(outputBase, target) : join8(outputBase, `course-${target}.zip`));
     const build = await packageLessonkit({
       interchange,
       spaDirs,
@@ -1315,17 +1513,24 @@ async function packageLessonkitCourse(options) {
     };
   }
   const descriptor = descriptorValidation.descriptor;
-  const nonInjectableAssessments = (descriptor.assessments ?? []).map((assessment, index) => ({ assessment, index })).filter(({ assessment }) => assessmentDescriptorToLxpack(assessment) === null);
-  if (nonInjectableAssessments.length > 0) {
-    return {
-      ok: false,
-      courseDir: outDir,
-      target,
-      issues: nonInjectableAssessments.map(({ assessment, index }) => ({
-        path: `assessments[${index}]`,
-        message: `assessment kind "${assessment.kind ?? "mcq"}" (checkId "${assessment.checkId}") is not injected into LMS shell quizzes for target "${target}"`
-      }))
-    };
+  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 staged = await buildStagingPackage({
     ...writeOpts,
@@ -1586,5 +1791,6 @@ export {
   validateLessonkitProject,
   validatePackageInputs,
   validateProjectPaths,
+  validateReactManifestParity,
   writeLxpackProject
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/lxpack",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "private": false,
   "description": "LXPack export adapter for LessonKit courses (SCORM, standalone, xAPI, cmi5).",
   "license": "Apache-2.0",
@@ -55,15 +55,15 @@
     "lint": "echo \"(no lint configured yet)\""
   },
   "dependencies": {
-    "@lessonkit/core": "1.3.0",
-    "@lessonkit/themes": "1.3.0",
-    "@lxpack/api": "^0.6.2",
-    "@lxpack/spa-bridge": "^0.6.2",
-    "@lxpack/tracking-schema": "^0.6.2",
-    "@lxpack/validators": "^0.6.2"
+    "@lessonkit/core": "1.4.0",
+    "@lessonkit/themes": "1.4.0",
+    "@lxpack/api": "0.6.4",
+    "@lxpack/spa-bridge": "0.6.4",
+    "@lxpack/tracking-schema": "0.6.4",
+    "@lxpack/validators": "0.6.4"
   },
   "devDependencies": {
-    "@types/node": "^22.13.10",
+    "@types/node": "^25.9.2",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^4.1.8"