@lessonkit/lxpack 0.7.0 → 0.8.1

package/README.md

@@ -1,9 +1,15 @@
 # @lessonkit/lxpack
 
+[![Documentation](https://readthedocs.org/projects/lessonkit/badge/?version=latest)](https://lessonkit.readthedocs.io/en/latest/)
+[![npm](https://img.shields.io/npm/v/@lessonkit/lxpack.svg)](https://www.npmjs.com/package/@lessonkit/lxpack)
+[![License](https://img.shields.io/github/license/eddiethedean/lessonkit)](https://github.com/eddiethedean/lessonkit/blob/main/LICENSE)
+
 LXPack export adapter for LessonKit — write `lessonkit.json` + `course.yaml`, copy SPA builds, and package to SCORM / standalone / xAPI / cmi5 via [`@lxpack/api`](https://www.npmjs.com/package/@lxpack/api).
 
 Requires **Node.js 20+**.
 
+**Docs:** [Packaging reference](https://lessonkit.readthedocs.io/en/latest/reference/packaging.html) · [Packaging & CLI guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/packaging-and-cli.html) · [Live examples](https://lessonkit.readthedocs.io/en/latest/examples/index.html)
+
 ## Install
 
 ```bash
@@ -27,7 +33,7 @@ const result = await packageLessonkitCourse({
 if (!result.ok) throw new Error("packaging failed");
 ```
 
-See [`docs/PACKAGING.md`](../../docs/PACKAGING.md) and [`examples/lxpack-golden`](../../examples/lxpack-golden).
+See the [packaging reference](https://lessonkit.readthedocs.io/en/latest/reference/packaging.html) and the [`examples/lxpack-golden`](https://github.com/eddiethedean/lessonkit/tree/main/examples/lxpack-golden) course.
 
 ## Browser bridge
 
@@ -38,3 +44,5 @@ import { notifyLxpackLessonComplete } from "@lessonkit/lxpack/bridge";
 ```
 
 `@lessonkit/react` forwards `lesson_completed`, `course_completed`, and `quiz_completed` automatically when `window.parent.lxpackBridge.v1` is present (`config.lxpack.bridge: "off"` to disable).
+
+For interoperability notes, see [LXPack upgrades](https://lessonkit.readthedocs.io/en/latest/reference/lxpack-upgrades.html). LXPack maintainers: [upgrade plan for maintainers](https://github.com/eddiethedean/lessonkit/blob/main/docs/LXPACK_UPGRADE_PLAN_FOR_MAINTAINERS.md).

package/dist/bridge.cjs

@@ -33,10 +33,15 @@ function normalizeAssessmentScore(opts) {
     return null;
   }
   const maxScore = typeof opts.maxScore === "number" && opts.maxScore > 0 ? opts.maxScore : 1;
-  return opts.score / maxScore;
+  return Math.min(1, opts.score / maxScore);
 }
-function normalizeAssessmentPassingScore(passingScore) {
-  return typeof passingScore === "number" && passingScore > 0 ? passingScore : 1;
+function normalizeAssessmentPassingScore(opts) {
+  const passingScore = opts?.passingScore;
+  if (typeof passingScore !== "number" || !Number.isFinite(passingScore) || passingScore <= 0) {
+    return 1;
+  }
+  const maxScore = typeof opts?.maxScore === "number" && opts.maxScore > 0 ? opts.maxScore : 1;
+  return Math.min(1, passingScore / maxScore);
 }
 function getBridge() {
   if (typeof window === "undefined") return null;

package/dist/bridge.d.cts

@@ -28,8 +28,14 @@ declare function normalizeAssessmentScore(opts: {
     score?: number;
     maxScore?: number;
 }): number | null;
-/** Bridge passing threshold (0–1 scale). Defaults to 1 when omitted or invalid. */
-declare function normalizeAssessmentPassingScore(passingScore?: number): number;
+/**
+ * Scale a raw passing threshold to 0–1 for the LXPack parent bridge.
+ * Uses the same `maxScore` denominator as `normalizeAssessmentScore`. Defaults to 1 when omitted or invalid.
+ */
+declare function normalizeAssessmentPassingScore(opts?: {
+    passingScore?: number;
+    maxScore?: number;
+}): number;
 declare function createLxpackBridge(): LxpackBridgeV1 | null;
 declare function notifyLxpackLessonComplete(lessonId: LessonId): boolean;
 declare function notifyLxpackCourseComplete(): boolean;

package/dist/bridge.d.ts

@@ -28,8 +28,14 @@ declare function normalizeAssessmentScore(opts: {
     score?: number;
     maxScore?: number;
 }): number | null;
-/** Bridge passing threshold (0–1 scale). Defaults to 1 when omitted or invalid. */
-declare function normalizeAssessmentPassingScore(passingScore?: number): number;
+/**
+ * Scale a raw passing threshold to 0–1 for the LXPack parent bridge.
+ * Uses the same `maxScore` denominator as `normalizeAssessmentScore`. Defaults to 1 when omitted or invalid.
+ */
+declare function normalizeAssessmentPassingScore(opts?: {
+    passingScore?: number;
+    maxScore?: number;
+}): number;
 declare function createLxpackBridge(): LxpackBridgeV1 | null;
 declare function notifyLxpackLessonComplete(lessonId: LessonId): boolean;
 declare function notifyLxpackCourseComplete(): boolean;

package/dist/bridge.js

@@ -4,10 +4,15 @@ function normalizeAssessmentScore(opts) {
     return null;
   }
   const maxScore = typeof opts.maxScore === "number" && opts.maxScore > 0 ? opts.maxScore : 1;
-  return opts.score / maxScore;
+  return Math.min(1, opts.score / maxScore);
 }
-function normalizeAssessmentPassingScore(passingScore) {
-  return typeof passingScore === "number" && passingScore > 0 ? passingScore : 1;
+function normalizeAssessmentPassingScore(opts) {
+  const passingScore = opts?.passingScore;
+  if (typeof passingScore !== "number" || !Number.isFinite(passingScore) || passingScore <= 0) {
+    return 1;
+  }
+  const maxScore = typeof opts?.maxScore === "number" && opts.maxScore > 0 ? opts.maxScore : 1;
+  return Math.min(1, passingScore / maxScore);
 }
 function getBridge() {
   if (typeof window === "undefined") return null;

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -26,10 +36,12 @@ __export(index_exports, {
   extractAssessments: () => extractAssessments,
   mapLessonkitIds: () => mapLessonkitIds,
   packageLessonkitCourse: () => packageLessonkitCourse,
+  resolveSafePackageOutputOverride: () => resolveSafePackageOutputOverride,
   resolveSpaLessons: () => resolveSpaLessons,
   themeToLxpackRuntime: () => themeToLxpackRuntime,
   validateDescriptor: () => validateDescriptor,
   validateLessonkitProject: () => validateLessonkitProject,
+  validateProjectPaths: () => validateProjectPaths,
   writeLxpackProject: () => writeLxpackProject
 });
 module.exports = __toCommonJS(index_exports);
@@ -43,8 +55,8 @@ function isSafeRelativeSpaPath(spaPath) {
   if (!spaPath.length || spaPath.includes("\0")) return false;
   if (spaPath.startsWith("/") || spaPath.startsWith("\\")) return false;
   if (/^[a-zA-Z]:[/\\]/.test(spaPath)) return false;
-  const segments = spaPath.split(/[/\\]/);
-  if (segments.some((s) => s === "..")) return false;
+  const segments = spaPath.split(/[/\\]/).filter((s) => s.length > 0);
+  if (segments.some((s) => s === ".." || s === ".")) return false;
   return true;
 }
 function assertResolvedPathUnderRoot(root, target) {
@@ -56,6 +68,21 @@ function assertResolvedPathUnderRoot(root, target) {
   }
 }
 
+// src/theme.ts
+var import_themes = require("@lessonkit/themes");
+function themeToLxpackRuntime(input) {
+  const theme = input.theme ?? (0, import_themes.getPresetTheme)(input.preset ?? "default");
+  const raw = (0, import_themes.themeToCssVariables)(theme);
+  const cssVariables = {};
+  for (const [key, value] of Object.entries(raw)) {
+    cssVariables[key] = String(value);
+  }
+  return {
+    theme: theme.name,
+    cssVariables
+  };
+}
+
 // src/validateDescriptor.ts
 var VALID_LAYOUTS = ["single-spa", "per-lesson-spa"];
 var VALID_THEME_PRESETS = ["default", "light", "dark", "brand"];
@@ -117,6 +144,25 @@ function validateDescriptor(input) {
       message: `unknown preset; use one of: ${VALID_THEME_PRESETS.join(", ")}`
     });
   }
+  if (input.theme?.theme) {
+    try {
+      themeToLxpackRuntime({ preset: themePreset, theme: input.theme.theme });
+    } catch (err) {
+      issues.push({
+        path: "theme.theme",
+        message: err instanceof Error ? err.message : "invalid custom theme"
+      });
+    }
+  }
+  const completionThreshold = input.tracking?.completion?.threshold;
+  if (completionThreshold !== void 0) {
+    if (!Number.isFinite(completionThreshold) || completionThreshold < 0 || completionThreshold > 1) {
+      issues.push({
+        path: "tracking.completion.threshold",
+        message: "threshold must be a finite number between 0 and 1"
+      });
+    }
+  }
   if (layout === "single-spa" && (input.lessons?.length ?? 0) > 1) {
     issues.push({
       path: "lessons",
@@ -196,24 +242,69 @@ function validateDescriptor(input) {
       issues.push({ path: `${path}.answer`, message: "answer must match a choice" });
     }
     const passingScore = assessment.passingScore;
-    if (passingScore !== void 0) {
-      if (!(passingScore > 0)) {
-        issues.push({
-          path: `${path}.passingScore`,
-          message: "passingScore must be greater than 0"
-        });
-      } else if (trimmedChoices.length && passingScore > trimmedChoices.length) {
-        issues.push({
-          path: `${path}.passingScore`,
-          message: "passingScore must not exceed the number of choices"
-        });
-      }
+    if (passingScore !== void 0 && !(passingScore > 0)) {
+      issues.push({
+        path: `${path}.passingScore`,
+        message: "passingScore must be greater than 0 (absolute point threshold)"
+      });
     }
   }
   if (issues.length) return { ok: false, issues };
   return { ok: true, descriptor: normalizeDescriptor(input) };
 }
 
+// src/validateProjectPaths.ts
+var import_node_path2 = require("path");
+function validatePathField(value, fieldPath, projectRoot, issues) {
+  if (!isSafeRelativeSpaPath(value)) {
+    issues.push({
+      path: fieldPath,
+      message: "path must be relative without '..' segments or absolute prefixes"
+    });
+    return;
+  }
+  try {
+    assertResolvedPathUnderRoot(projectRoot, (0, import_node_path2.resolve)(projectRoot, value));
+  } catch {
+    issues.push({
+      path: fieldPath,
+      message: "path must resolve inside the project root"
+    });
+  }
+}
+function validateProjectPaths(projectRoot, paths) {
+  const issues = [];
+  const root = (0, import_node_path2.resolve)(projectRoot);
+  if (paths.spaDistDir?.trim()) {
+    validatePathField(paths.spaDistDir.trim(), "paths.spaDistDir", root, issues);
+  }
+  if (paths.lxpackOutDir?.trim()) {
+    validatePathField(paths.lxpackOutDir.trim(), "paths.lxpackOutDir", root, issues);
+  }
+  if (paths.outputBaseDir?.trim()) {
+    validatePathField(paths.outputBaseDir.trim(), "paths.outputBaseDir", root, issues);
+  }
+  return issues;
+}
+function resolveSafePackageOutputOverride(projectRoot, override) {
+  const root = (0, import_node_path2.resolve)(projectRoot);
+  const trimmed = override.trim();
+  if (!trimmed) {
+    throw new Error("output override must be a non-empty path");
+  }
+  if ((0, import_node_path2.isAbsolute)(trimmed)) {
+    const resolved2 = (0, import_node_path2.resolve)(trimmed);
+    assertResolvedPathUnderRoot(root, resolved2);
+    return resolved2;
+  }
+  if (!isSafeRelativeSpaPath(trimmed)) {
+    throw new Error(`unsafe output path: ${override}`);
+  }
+  const resolved = (0, import_node_path2.resolve)(root, trimmed);
+  assertResolvedPathUnderRoot(root, resolved);
+  return resolved;
+}
+
 // src/mapIds.ts
 var import_core2 = require("@lessonkit/core");
 function mapLessonkitIds(descriptor) {
@@ -225,21 +316,6 @@ function mapLessonkitIds(descriptor) {
   return { courseId, lessonIds, checkIds };
 }
 
-// src/theme.ts
-var import_themes = require("@lessonkit/themes");
-function themeToLxpackRuntime(input) {
-  const theme = input.theme ?? (0, import_themes.getPresetTheme)(input.preset ?? "default");
-  const raw = (0, import_themes.themeToCssVariables)(theme);
-  const cssVariables = {};
-  for (const [key, value] of Object.entries(raw)) {
-    cssVariables[key] = String(value);
-  }
-  return {
-    theme: theme.name,
-    cssVariables
-  };
-}
-
 // src/interchange.ts
 function resolveSpaLessons(descriptor) {
   const mapped = mapLessonkitIds(descriptor);
@@ -313,7 +389,7 @@ function extractAssessments(descriptor) {
 
 // src/writeProject.ts
 var import_promises = require("fs/promises");
-var import_node_path2 = require("path");
+var import_node_path3 = require("path");
 
 // src/assessmentYaml.ts
 function yamlQuote(value) {
@@ -388,7 +464,7 @@ function emitCourseYaml(opts) {
 
 // src/writeProject.ts
 async function copyDir(src, dest) {
-  await (0, import_promises.mkdir)((0, import_node_path2.dirname)(dest), { recursive: true });
+  await (0, import_promises.mkdir)((0, import_node_path3.dirname)(dest), { recursive: true });
   await (0, import_promises.cp)(src, dest, { recursive: true });
 }
 async function writeLxpackProject(options) {
@@ -399,7 +475,7 @@ async function writeLxpackProject(options) {
     );
   }
   const descriptor = validation.descriptor;
-  const outDir = (0, import_node_path2.resolve)(options.outDir);
+  const outDir = (0, import_node_path3.resolve)(options.outDir);
   await (0, import_promises.mkdir)(outDir, { recursive: true });
   const spaLessons = resolveSpaLessons(descriptor);
   const runtime = descriptor.theme ? themeToLxpackRuntime(descriptor.theme) : void 0;
@@ -408,13 +484,17 @@ async function writeLxpackProject(options) {
     file: `assessments/${a.checkId}.yaml`
   }));
   if (descriptor.layout === "single-spa") {
-    const srcDist = (0, import_node_path2.resolve)(options.spaDistDir ?? descriptor.spaDistDir ?? "dist");
+    const spaDistRelative = options.spaDistDir ?? descriptor.spaDistDir ?? "dist";
+    const srcDist = options.projectRoot ? (0, import_node_path3.resolve)(options.projectRoot, spaDistRelative) : (0, import_node_path3.resolve)(spaDistRelative);
+    if (options.projectRoot) {
+      assertResolvedPathUnderRoot((0, import_node_path3.resolve)(options.projectRoot), srcDist);
+    }
     try {
       await (0, import_promises.access)(srcDist);
     } catch {
       throw new Error(`spaDistDir not found: ${srcDist}`);
     }
-    const destDist = (0, import_node_path2.join)(outDir, "dist");
+    const destDist = (0, import_node_path3.join)(outDir, "dist");
     await (0, import_promises.rm)(destDist, { recursive: true, force: true });
     await copyDir(srcDist, destDist);
   } else {
@@ -424,24 +504,24 @@ async function writeLxpackProject(options) {
       if (!src) {
         throw new Error(`lessonSpaDirs missing build output for lesson "${lesson.id}"`);
       }
-      const dest = (0, import_node_path2.join)(outDir, lesson.spaPath);
+      const dest = (0, import_node_path3.join)(outDir, lesson.spaPath);
       assertResolvedPathUnderRoot(outDir, dest);
       await (0, import_promises.rm)(dest, { recursive: true, force: true });
-      await copyDir((0, import_node_path2.resolve)(src), dest);
+      await copyDir((0, import_node_path3.resolve)(src), dest);
     }
   }
   if (assessments.length) {
-    const assessmentsDir = (0, import_node_path2.join)(outDir, "assessments");
+    const assessmentsDir = (0, import_node_path3.join)(outDir, "assessments");
     await (0, import_promises.mkdir)(assessmentsDir, { recursive: true });
     for (const assessment of descriptor.assessments ?? []) {
       await (0, import_promises.writeFile)(
-        (0, import_node_path2.join)(outDir, `assessments/${assessment.checkId}.yaml`),
+        (0, import_node_path3.join)(outDir, `assessments/${assessment.checkId}.yaml`),
         emitAssessmentYaml(assessment),
         "utf-8"
       );
     }
   }
-  const courseYamlPath = (0, import_node_path2.join)(outDir, "course.yaml");
+  const courseYamlPath = (0, import_node_path3.join)(outDir, "course.yaml");
   await (0, import_promises.writeFile)(
     courseYamlPath,
     emitCourseYaml({
@@ -459,7 +539,7 @@ async function writeLxpackProject(options) {
     }),
     "utf-8"
   );
-  const lessonkitJsonPath = (0, import_node_path2.join)(outDir, "lessonkit.json");
+  const lessonkitJsonPath = (0, import_node_path3.join)(outDir, "lessonkit.json");
   await (0, import_promises.writeFile)(
     lessonkitJsonPath,
     `${JSON.stringify(descriptorToInterchange(descriptor), null, 2)}
@@ -470,19 +550,19 @@ async function writeLxpackProject(options) {
 }
 
 // src/packageCourse.ts
-var import_promises2 = require("fs/promises");
-var import_node_path3 = require("path");
+var fsp = __toESM(require("fs/promises"), 1);
+var import_node_path4 = require("path");
 var import_node_os = require("os");
 var import_api = require("@lxpack/api");
 async function validateLessonkitProject(options) {
   return (0, import_api.validateCourse)({
-    courseDir: (0, import_node_path3.resolve)(options.courseDir),
+    courseDir: (0, import_node_path4.resolve)(options.courseDir),
     target: options.target
   });
 }
 async function buildLessonkitProject(options) {
   return (0, import_api.buildCourse)({
-    courseDir: (0, import_node_path3.resolve)(options.courseDir),
+    courseDir: (0, import_node_path4.resolve)(options.courseDir),
     target: options.target,
     output: options.output,
     dir: options.dir,
@@ -490,9 +570,38 @@ async function buildLessonkitProject(options) {
     assessments: options.assessments
   });
 }
+async function pathExists(path) {
+  try {
+    await fsp.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function promoteStagingToOutDir(stagingDir, outDir) {
+  const tmpPromote = `${outDir}.tmp-promote`;
+  const backup = `${outDir}.bak`;
+  await fsp.rename(stagingDir, tmpPromote);
+  const hadOutDir = await pathExists(outDir);
+  if (hadOutDir) {
+    await fsp.rename(outDir, backup);
+  }
+  try {
+    await fsp.rename(tmpPromote, outDir);
+  } catch (promoteError) {
+    if (hadOutDir) {
+      await fsp.rename(backup, outDir).catch(() => void 0);
+    }
+    await fsp.rm(tmpPromote, { recursive: true, force: true }).catch(() => void 0);
+    throw promoteError;
+  }
+  if (hadOutDir) {
+    await fsp.rm(backup, { recursive: true, force: true }).catch(() => void 0);
+  }
+}
 async function packageLessonkitCourse(options) {
   const { target, output, dir, outputBaseDir, ...writeOpts } = options;
-  const outDir = (0, import_node_path3.resolve)(writeOpts.outDir);
+  const outDir = (0, import_node_path4.resolve)(writeOpts.outDir);
   const descriptorValidation = validateDescriptor(writeOpts.descriptor);
   if (!descriptorValidation.ok) {
     return {
@@ -506,7 +615,7 @@ async function packageLessonkitCourse(options) {
     };
   }
   const descriptor = descriptorValidation.descriptor;
-  const stagingDir = await (0, import_promises2.mkdtemp)((0, import_node_path3.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
+  const stagingDir = await fsp.mkdtemp((0, import_node_path4.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
   let promoted = false;
   try {
     const written = await writeLxpackProject({ ...writeOpts, descriptor, outDir: stagingDir });
@@ -527,12 +636,12 @@ async function packageLessonkitCourse(options) {
       };
     }
     const outputBase = outputBaseDir ?? ".lxpack/out";
-    await (0, import_promises2.mkdir)((0, import_node_path3.join)(courseDir, outputBase), { recursive: true });
-    const defaultOutput = output ?? (dir ? (0, import_node_path3.join)(outputBase, target) : (0, import_node_path3.join)(outputBase, `course-${target}.zip`));
+    await fsp.mkdir((0, import_node_path4.join)(courseDir, outputBase), { recursive: true });
+    const defaultOutput = output ?? (dir ? (0, import_node_path4.join)(outputBase, target) : (0, import_node_path4.join)(outputBase, `course-${target}.zip`));
     const build = await buildLessonkitProject({
       courseDir,
       target,
-      output: defaultOutput.startsWith("/") ? defaultOutput : (0, import_node_path3.join)(courseDir, defaultOutput),
+      output: defaultOutput.startsWith("/") ? defaultOutput : (0, import_node_path4.join)(courseDir, defaultOutput),
       dir,
       assessments: assessments.length ? assessments : void 0
     });
@@ -550,32 +659,42 @@ async function packageLessonkitCourse(options) {
         }))
       };
     }
-    await (0, import_promises2.rm)(outDir, { recursive: true, force: true });
-    await (0, import_promises2.mkdir)((0, import_node_path3.dirname)(outDir), { recursive: true });
-    await (0, import_promises2.rename)(stagingDir, outDir);
+    await fsp.mkdir((0, import_node_path4.dirname)(outDir), { recursive: true });
+    await promoteStagingToOutDir(stagingDir, outDir);
     promoted = true;
     const remapArtifactPath = (artifactPath) => {
       if (!artifactPath) return void 0;
-      const resolved = (0, import_node_path3.resolve)(artifactPath);
-      const stagingResolved = (0, import_node_path3.resolve)(stagingDir);
+      const resolved = (0, import_node_path4.resolve)(artifactPath);
+      const stagingResolved = (0, import_node_path4.resolve)(stagingDir);
       if (resolved === stagingResolved || resolved.startsWith(stagingResolved + "/")) {
-        return (0, import_node_path3.join)(outDir, resolved.slice(stagingResolved.length + 1));
+        return (0, import_node_path4.join)(outDir, resolved.slice(stagingResolved.length + 1));
       }
       return artifactPath;
     };
+    const remappedOutputPath = remapArtifactPath(
+      "outputPath" in build ? build.outputPath : void 0
+    );
+    const remappedOutputDir = remapArtifactPath("outputDir" in build ? build.outputDir : void 0);
+    const remappedBuild = { ...build };
+    if ("outputPath" in remappedBuild && remappedOutputPath !== void 0) {
+      remappedBuild.outputPath = remappedOutputPath;
+    }
+    if ("outputDir" in remappedBuild && remappedOutputDir !== void 0) {
+      remappedBuild.outputDir = remappedOutputDir;
+    }
     return {
       ok: true,
       courseDir: outDir,
       target,
-      outputPath: remapArtifactPath("outputPath" in build ? build.outputPath : void 0),
-      outputDir: remapArtifactPath("outputDir" in build ? build.outputDir : void 0),
+      outputPath: remappedOutputPath,
+      outputDir: remappedOutputDir,
       fileCount: build.fileCount,
       validation,
-      build
+      build: remappedBuild
     };
   } finally {
     if (!promoted) {
-      await (0, import_promises2.rm)(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+      await fsp.rm(stagingDir, { recursive: true, force: true }).catch(() => void 0);
     }
   }
 }
@@ -587,9 +706,11 @@ async function packageLessonkitCourse(options) {
   extractAssessments,
   mapLessonkitIds,
   packageLessonkitCourse,
+  resolveSafePackageOutputOverride,
   resolveSpaLessons,
   themeToLxpackRuntime,
   validateDescriptor,
   validateLessonkitProject,
+  validateProjectPaths,
   writeLxpackProject
 });

package/dist/index.d.cts

@@ -76,6 +76,18 @@ type DescriptorValidationResult = {
 };
 declare function validateDescriptor(input: LessonkitCourseDescriptor): DescriptorValidationResult;
 
+type ProjectPathsInput = {
+    spaDistDir?: string;
+    lxpackOutDir?: string;
+    outputBaseDir?: string;
+};
+/** Validate lessonkit.json paths.* entries stay under projectRoot. */
+declare function validateProjectPaths(projectRoot: string, paths: ProjectPathsInput): DescriptorValidationIssue[];
+/**
+ * Resolve a package --out override under projectRoot and ensure it stays inside the project.
+ */
+declare function resolveSafePackageOutputOverride(projectRoot: string, override: string): string;
+
 /**
  * Stable 1:1 mapping from LessonKit ids to LXPack manifest ids.
  * LessonKit slug rules already match LXPack `activityIdSchema` (letter-first, alphanumeric + _ -).
@@ -129,6 +141,8 @@ type WriteLxpackProjectOptions = {
      * For `per-lesson-spa`: map lesson id → absolute path to that lesson's built SPA folder.
      */
     lessonSpaDirs?: Record<string, string>;
+    /** When set, relative `spaDistDir` is resolved under this directory instead of `process.cwd()`. */
+    projectRoot?: string;
 };
 type WriteLxpackProjectResult = {
     outDir: string;
@@ -181,4 +195,4 @@ declare function validateLessonkitProject(options: ValidateLessonkitProjectOptio
 declare function buildLessonkitProject(options: BuildLessonkitProjectOptions): Promise<BuildCourseResult>;
 declare function packageLessonkitCourse(options: PackageLessonkitCourseOptions): Promise<PackageLessonkitCourseResult>;
 
-export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type DescriptorValidationIssue, type DescriptorValidationResult, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitInterchangeV1, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type MappedLessonkitIds, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type SpaLayout, type SpaLessonEntry, type ValidateLessonkitProjectOptions, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, descriptorToInterchange, extractAssessments, mapLessonkitIds, packageLessonkitCourse, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateLessonkitProject, writeLxpackProject };
+export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type DescriptorValidationIssue, type DescriptorValidationResult, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitInterchangeV1, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type MappedLessonkitIds, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type ProjectPathsInput, type SpaLayout, type SpaLessonEntry, type ValidateLessonkitProjectOptions, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, descriptorToInterchange, extractAssessments, mapLessonkitIds, packageLessonkitCourse, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateLessonkitProject, validateProjectPaths, writeLxpackProject };

package/dist/index.d.ts

@@ -76,6 +76,18 @@ type DescriptorValidationResult = {
 };
 declare function validateDescriptor(input: LessonkitCourseDescriptor): DescriptorValidationResult;
 
+type ProjectPathsInput = {
+    spaDistDir?: string;
+    lxpackOutDir?: string;
+    outputBaseDir?: string;
+};
+/** Validate lessonkit.json paths.* entries stay under projectRoot. */
+declare function validateProjectPaths(projectRoot: string, paths: ProjectPathsInput): DescriptorValidationIssue[];
+/**
+ * Resolve a package --out override under projectRoot and ensure it stays inside the project.
+ */
+declare function resolveSafePackageOutputOverride(projectRoot: string, override: string): string;
+
 /**
  * Stable 1:1 mapping from LessonKit ids to LXPack manifest ids.
  * LessonKit slug rules already match LXPack `activityIdSchema` (letter-first, alphanumeric + _ -).
@@ -129,6 +141,8 @@ type WriteLxpackProjectOptions = {
      * For `per-lesson-spa`: map lesson id → absolute path to that lesson's built SPA folder.
      */
     lessonSpaDirs?: Record<string, string>;
+    /** When set, relative `spaDistDir` is resolved under this directory instead of `process.cwd()`. */
+    projectRoot?: string;
 };
 type WriteLxpackProjectResult = {
     outDir: string;
@@ -181,4 +195,4 @@ declare function validateLessonkitProject(options: ValidateLessonkitProjectOptio
 declare function buildLessonkitProject(options: BuildLessonkitProjectOptions): Promise<BuildCourseResult>;
 declare function packageLessonkitCourse(options: PackageLessonkitCourseOptions): Promise<PackageLessonkitCourseResult>;
 
-export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type DescriptorValidationIssue, type DescriptorValidationResult, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitInterchangeV1, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type MappedLessonkitIds, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type SpaLayout, type SpaLessonEntry, type ValidateLessonkitProjectOptions, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, descriptorToInterchange, extractAssessments, mapLessonkitIds, packageLessonkitCourse, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateLessonkitProject, writeLxpackProject };
+export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type DescriptorValidationIssue, type DescriptorValidationResult, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitInterchangeV1, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type MappedLessonkitIds, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type ProjectPathsInput, type SpaLayout, type SpaLessonEntry, type ValidateLessonkitProjectOptions, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, descriptorToInterchange, extractAssessments, mapLessonkitIds, packageLessonkitCourse, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateLessonkitProject, validateProjectPaths, writeLxpackProject };

package/dist/index.js

@@ -7,8 +7,8 @@ function isSafeRelativeSpaPath(spaPath) {
   if (!spaPath.length || spaPath.includes("\0")) return false;
   if (spaPath.startsWith("/") || spaPath.startsWith("\\")) return false;
   if (/^[a-zA-Z]:[/\\]/.test(spaPath)) return false;
-  const segments = spaPath.split(/[/\\]/);
-  if (segments.some((s) => s === "..")) return false;
+  const segments = spaPath.split(/[/\\]/).filter((s) => s.length > 0);
+  if (segments.some((s) => s === ".." || s === ".")) return false;
   return true;
 }
 function assertResolvedPathUnderRoot(root, target) {
@@ -20,6 +20,21 @@ function assertResolvedPathUnderRoot(root, target) {
   }
 }
 
+// src/theme.ts
+import { getPresetTheme, themeToCssVariables } from "@lessonkit/themes";
+function themeToLxpackRuntime(input) {
+  const theme = input.theme ?? getPresetTheme(input.preset ?? "default");
+  const raw = themeToCssVariables(theme);
+  const cssVariables = {};
+  for (const [key, value] of Object.entries(raw)) {
+    cssVariables[key] = String(value);
+  }
+  return {
+    theme: theme.name,
+    cssVariables
+  };
+}
+
 // src/validateDescriptor.ts
 var VALID_LAYOUTS = ["single-spa", "per-lesson-spa"];
 var VALID_THEME_PRESETS = ["default", "light", "dark", "brand"];
@@ -81,6 +96,25 @@ function validateDescriptor(input) {
       message: `unknown preset; use one of: ${VALID_THEME_PRESETS.join(", ")}`
     });
   }
+  if (input.theme?.theme) {
+    try {
+      themeToLxpackRuntime({ preset: themePreset, theme: input.theme.theme });
+    } catch (err) {
+      issues.push({
+        path: "theme.theme",
+        message: err instanceof Error ? err.message : "invalid custom theme"
+      });
+    }
+  }
+  const completionThreshold = input.tracking?.completion?.threshold;
+  if (completionThreshold !== void 0) {
+    if (!Number.isFinite(completionThreshold) || completionThreshold < 0 || completionThreshold > 1) {
+      issues.push({
+        path: "tracking.completion.threshold",
+        message: "threshold must be a finite number between 0 and 1"
+      });
+    }
+  }
   if (layout === "single-spa" && (input.lessons?.length ?? 0) > 1) {
     issues.push({
       path: "lessons",
@@ -160,24 +194,69 @@ function validateDescriptor(input) {
       issues.push({ path: `${path}.answer`, message: "answer must match a choice" });
     }
     const passingScore = assessment.passingScore;
-    if (passingScore !== void 0) {
-      if (!(passingScore > 0)) {
-        issues.push({
-          path: `${path}.passingScore`,
-          message: "passingScore must be greater than 0"
-        });
-      } else if (trimmedChoices.length && passingScore > trimmedChoices.length) {
-        issues.push({
-          path: `${path}.passingScore`,
-          message: "passingScore must not exceed the number of choices"
-        });
-      }
+    if (passingScore !== void 0 && !(passingScore > 0)) {
+      issues.push({
+        path: `${path}.passingScore`,
+        message: "passingScore must be greater than 0 (absolute point threshold)"
+      });
     }
   }
   if (issues.length) return { ok: false, issues };
   return { ok: true, descriptor: normalizeDescriptor(input) };
 }
 
+// src/validateProjectPaths.ts
+import { isAbsolute, resolve as resolve2 } from "path";
+function validatePathField(value, fieldPath, projectRoot, issues) {
+  if (!isSafeRelativeSpaPath(value)) {
+    issues.push({
+      path: fieldPath,
+      message: "path must be relative without '..' segments or absolute prefixes"
+    });
+    return;
+  }
+  try {
+    assertResolvedPathUnderRoot(projectRoot, resolve2(projectRoot, value));
+  } catch {
+    issues.push({
+      path: fieldPath,
+      message: "path must resolve inside the project root"
+    });
+  }
+}
+function validateProjectPaths(projectRoot, paths) {
+  const issues = [];
+  const root = resolve2(projectRoot);
+  if (paths.spaDistDir?.trim()) {
+    validatePathField(paths.spaDistDir.trim(), "paths.spaDistDir", root, issues);
+  }
+  if (paths.lxpackOutDir?.trim()) {
+    validatePathField(paths.lxpackOutDir.trim(), "paths.lxpackOutDir", root, issues);
+  }
+  if (paths.outputBaseDir?.trim()) {
+    validatePathField(paths.outputBaseDir.trim(), "paths.outputBaseDir", root, issues);
+  }
+  return issues;
+}
+function resolveSafePackageOutputOverride(projectRoot, override) {
+  const root = resolve2(projectRoot);
+  const trimmed = override.trim();
+  if (!trimmed) {
+    throw new Error("output override must be a non-empty path");
+  }
+  if (isAbsolute(trimmed)) {
+    const resolved2 = resolve2(trimmed);
+    assertResolvedPathUnderRoot(root, resolved2);
+    return resolved2;
+  }
+  if (!isSafeRelativeSpaPath(trimmed)) {
+    throw new Error(`unsafe output path: ${override}`);
+  }
+  const resolved = resolve2(root, trimmed);
+  assertResolvedPathUnderRoot(root, resolved);
+  return resolved;
+}
+
 // src/mapIds.ts
 import { assertValidId } from "@lessonkit/core";
 function mapLessonkitIds(descriptor) {
@@ -189,21 +268,6 @@ function mapLessonkitIds(descriptor) {
   return { courseId, lessonIds, checkIds };
 }
 
-// src/theme.ts
-import { getPresetTheme, themeToCssVariables } from "@lessonkit/themes";
-function themeToLxpackRuntime(input) {
-  const theme = input.theme ?? getPresetTheme(input.preset ?? "default");
-  const raw = themeToCssVariables(theme);
-  const cssVariables = {};
-  for (const [key, value] of Object.entries(raw)) {
-    cssVariables[key] = String(value);
-  }
-  return {
-    theme: theme.name,
-    cssVariables
-  };
-}
-
 // src/interchange.ts
 function resolveSpaLessons(descriptor) {
   const mapped = mapLessonkitIds(descriptor);
@@ -277,7 +341,7 @@ function extractAssessments(descriptor) {
 
 // src/writeProject.ts
 import { access, cp, mkdir, rm, writeFile } from "fs/promises";
-import { dirname, join, resolve as resolve2 } from "path";
+import { dirname, join, resolve as resolve3 } from "path";
 
 // src/assessmentYaml.ts
 function yamlQuote(value) {
@@ -363,7 +427,7 @@ async function writeLxpackProject(options) {
     );
   }
   const descriptor = validation.descriptor;
-  const outDir = resolve2(options.outDir);
+  const outDir = resolve3(options.outDir);
   await mkdir(outDir, { recursive: true });
   const spaLessons = resolveSpaLessons(descriptor);
   const runtime = descriptor.theme ? themeToLxpackRuntime(descriptor.theme) : void 0;
@@ -372,7 +436,11 @@ async function writeLxpackProject(options) {
     file: `assessments/${a.checkId}.yaml`
   }));
   if (descriptor.layout === "single-spa") {
-    const srcDist = resolve2(options.spaDistDir ?? descriptor.spaDistDir ?? "dist");
+    const spaDistRelative = options.spaDistDir ?? descriptor.spaDistDir ?? "dist";
+    const srcDist = options.projectRoot ? resolve3(options.projectRoot, spaDistRelative) : resolve3(spaDistRelative);
+    if (options.projectRoot) {
+      assertResolvedPathUnderRoot(resolve3(options.projectRoot), srcDist);
+    }
     try {
       await access(srcDist);
     } catch {
@@ -391,7 +459,7 @@ async function writeLxpackProject(options) {
       const dest = join(outDir, lesson.spaPath);
       assertResolvedPathUnderRoot(outDir, dest);
       await rm(dest, { recursive: true, force: true });
-      await copyDir(resolve2(src), dest);
+      await copyDir(resolve3(src), dest);
     }
   }
   if (assessments.length) {
@@ -434,8 +502,8 @@ async function writeLxpackProject(options) {
 }
 
 // src/packageCourse.ts
-import { mkdir as mkdir2, mkdtemp, rename, rm as rm2 } from "fs/promises";
-import { dirname as dirname2, join as join2, resolve as resolve3 } from "path";
+import * as fsp from "fs/promises";
+import { dirname as dirname2, join as join2, resolve as resolve4 } from "path";
 import { tmpdir } from "os";
 import {
   buildCourse,
@@ -443,13 +511,13 @@ import {
 } from "@lxpack/api";
 async function validateLessonkitProject(options) {
   return validateCourse({
-    courseDir: resolve3(options.courseDir),
+    courseDir: resolve4(options.courseDir),
     target: options.target
   });
 }
 async function buildLessonkitProject(options) {
   return buildCourse({
-    courseDir: resolve3(options.courseDir),
+    courseDir: resolve4(options.courseDir),
     target: options.target,
     output: options.output,
     dir: options.dir,
@@ -457,9 +525,38 @@ async function buildLessonkitProject(options) {
     assessments: options.assessments
   });
 }
+async function pathExists(path) {
+  try {
+    await fsp.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function promoteStagingToOutDir(stagingDir, outDir) {
+  const tmpPromote = `${outDir}.tmp-promote`;
+  const backup = `${outDir}.bak`;
+  await fsp.rename(stagingDir, tmpPromote);
+  const hadOutDir = await pathExists(outDir);
+  if (hadOutDir) {
+    await fsp.rename(outDir, backup);
+  }
+  try {
+    await fsp.rename(tmpPromote, outDir);
+  } catch (promoteError) {
+    if (hadOutDir) {
+      await fsp.rename(backup, outDir).catch(() => void 0);
+    }
+    await fsp.rm(tmpPromote, { recursive: true, force: true }).catch(() => void 0);
+    throw promoteError;
+  }
+  if (hadOutDir) {
+    await fsp.rm(backup, { recursive: true, force: true }).catch(() => void 0);
+  }
+}
 async function packageLessonkitCourse(options) {
   const { target, output, dir, outputBaseDir, ...writeOpts } = options;
-  const outDir = resolve3(writeOpts.outDir);
+  const outDir = resolve4(writeOpts.outDir);
   const descriptorValidation = validateDescriptor(writeOpts.descriptor);
   if (!descriptorValidation.ok) {
     return {
@@ -473,7 +570,7 @@ async function packageLessonkitCourse(options) {
     };
   }
   const descriptor = descriptorValidation.descriptor;
-  const stagingDir = await mkdtemp(join2(tmpdir(), "lessonkit-lxpack-"));
+  const stagingDir = await fsp.mkdtemp(join2(tmpdir(), "lessonkit-lxpack-"));
   let promoted = false;
   try {
     const written = await writeLxpackProject({ ...writeOpts, descriptor, outDir: stagingDir });
@@ -494,7 +591,7 @@ async function packageLessonkitCourse(options) {
       };
     }
     const outputBase = outputBaseDir ?? ".lxpack/out";
-    await mkdir2(join2(courseDir, outputBase), { recursive: true });
+    await fsp.mkdir(join2(courseDir, outputBase), { recursive: true });
     const defaultOutput = output ?? (dir ? join2(outputBase, target) : join2(outputBase, `course-${target}.zip`));
     const build = await buildLessonkitProject({
       courseDir,
@@ -517,32 +614,42 @@ async function packageLessonkitCourse(options) {
         }))
       };
     }
-    await rm2(outDir, { recursive: true, force: true });
-    await mkdir2(dirname2(outDir), { recursive: true });
-    await rename(stagingDir, outDir);
+    await fsp.mkdir(dirname2(outDir), { recursive: true });
+    await promoteStagingToOutDir(stagingDir, outDir);
     promoted = true;
     const remapArtifactPath = (artifactPath) => {
       if (!artifactPath) return void 0;
-      const resolved = resolve3(artifactPath);
-      const stagingResolved = resolve3(stagingDir);
+      const resolved = resolve4(artifactPath);
+      const stagingResolved = resolve4(stagingDir);
       if (resolved === stagingResolved || resolved.startsWith(stagingResolved + "/")) {
         return join2(outDir, resolved.slice(stagingResolved.length + 1));
       }
       return artifactPath;
     };
+    const remappedOutputPath = remapArtifactPath(
+      "outputPath" in build ? build.outputPath : void 0
+    );
+    const remappedOutputDir = remapArtifactPath("outputDir" in build ? build.outputDir : void 0);
+    const remappedBuild = { ...build };
+    if ("outputPath" in remappedBuild && remappedOutputPath !== void 0) {
+      remappedBuild.outputPath = remappedOutputPath;
+    }
+    if ("outputDir" in remappedBuild && remappedOutputDir !== void 0) {
+      remappedBuild.outputDir = remappedOutputDir;
+    }
     return {
       ok: true,
       courseDir: outDir,
       target,
-      outputPath: remapArtifactPath("outputPath" in build ? build.outputPath : void 0),
-      outputDir: remapArtifactPath("outputDir" in build ? build.outputDir : void 0),
+      outputPath: remappedOutputPath,
+      outputDir: remappedOutputDir,
       fileCount: build.fileCount,
       validation,
-      build
+      build: remappedBuild
     };
   } finally {
     if (!promoted) {
-      await rm2(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+      await fsp.rm(stagingDir, { recursive: true, force: true }).catch(() => void 0);
     }
   }
 }
@@ -553,9 +660,11 @@ export {
   extractAssessments,
   mapLessonkitIds,
   packageLessonkitCourse,
+  resolveSafePackageOutputOverride,
   resolveSpaLessons,
   themeToLxpackRuntime,
   validateDescriptor,
   validateLessonkitProject,
+  validateProjectPaths,
   writeLxpackProject
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/lxpack",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "private": false,
   "description": "LXPack export adapter for LessonKit courses (SCORM, standalone, xAPI, cmi5).",
   "license": "Apache-2.0",
@@ -53,8 +53,8 @@
     "lint": "echo \"(no lint configured yet)\""
   },
   "dependencies": {
-    "@lessonkit/core": "0.7.0",
-    "@lessonkit/themes": "0.7.0",
+    "@lessonkit/core": "0.8.1",
+    "@lessonkit/themes": "0.8.1",
     "@lxpack/api": "^0.4.0"
   },
   "devDependencies": {