@lessonkit/lxpack 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { CheckId, CourseId, LessonId } from '@lessonkit/core';
 import { ThemePresetName, LessonkitThemeV1 } from '@lessonkit/themes';
-import { LessonkitInterchangeV1 } from '@lxpack/validators';
-export { LessonkitInterchangeV1, MaterializeLessonkitOptions, MaterializeLessonkitResult, lessonkitInterchangeSchema, materializeLessonkitProject, parseLessonkitInterchange } from '@lxpack/validators';
 import { ExportTarget, BuildCourseResult, ValidateCourseResult } from '@lxpack/api';
 export { ExportTarget } from '@lxpack/api';
+import { LessonkitInterchangeV1 } from '@lxpack/validators';
+export { LessonkitInterchangeV1, MaterializeLessonkitOptions, MaterializeLessonkitResult, lessonkitInterchangeSchema, materializeLessonkitProject, parseLessonkitInterchange } from '@lxpack/validators';
 export { LESSONKIT_TELEMETRY_EVENTS, LessonkitBridgeAction, LessonkitTelemetryEvent, LessonkitTelemetryEventName, TrackingSchemaEvent, mapLessonkitTelemetryToBridgeAction, mapLessonkitTelemetryToLxpack } from '@lxpack/tracking-schema';
 export { t as telemetryEventToLessonkit } from './telemetry-gCxlwc7I.js';
 
@@ -53,10 +53,14 @@ type MappedLessonkitIds = {
     checkIds: CheckId[];
 };
 
-type DescriptorValidationIssue = {
+/** Shared validation issue shape across lxpack parsers. */
+type ValidationIssue = {
     path: string;
     message: string;
+    severity?: string;
 };
+
+type DescriptorValidationIssue = ValidationIssue;
 type DescriptorValidationResult = {
     ok: true;
     descriptor: LessonkitCourseDescriptor;
@@ -64,7 +68,8 @@ type DescriptorValidationResult = {
     ok: false;
     issues: DescriptorValidationIssue[];
 };
-declare function validateDescriptor(input: LessonkitCourseDescriptor): DescriptorValidationResult;
+declare function validateDescriptor(input: unknown): DescriptorValidationResult;
+declare function validateDescriptorForTarget(input: unknown, target?: ExportTarget): DescriptorValidationResult;
 
 type ProjectPathsInput = {
     spaDistDir?: string;
@@ -94,7 +99,7 @@ declare function themeToLxpackRuntime(input: {
 }): LxpackRuntimeTheme;
 
 type SpaLessonEntry = {
-    id: string;
+    id: LessonId;
     title: string;
     path: string;
 };
@@ -188,7 +193,7 @@ type BuildLessonkitProjectOptions = {
     output?: string;
     dir?: boolean;
     outputBaseDir?: string;
-    assessments?: unknown[];
+    assessments?: LxpackInjectedAssessment[];
 };
 type PackageLessonkitCourseOptions = WriteLxpackProjectOptions & {
     target: ExportTarget;
@@ -268,4 +273,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 LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type SpaLayout, type SpaLessonEntry, type ValidateLessonkitProjectOptions, type ValidatePackageInputsResult, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateLessonkitProject, validatePackageInputs, validateProjectPaths, writeLxpackProject };
+export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type SpaLayout, type SpaLessonEntry, 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 };

package/dist/index.js

@@ -1,13 +1,13 @@
 import {
   telemetryEventToLessonkit
-} from "./chunk-PSUSESH3.js";
+} from "./chunk-DYQI222N.js";
 
 // src/validateDescriptor.ts
 import { validateId } from "@lessonkit/core";
 
 // src/spaPath.ts
 import { realpathSync } from "fs";
-import { relative, resolve, sep, win32 } from "path";
+import { isAbsolute, relative, resolve, sep, win32 } from "path";
 function resolveComparablePath(p) {
   if (/^[a-zA-Z]:[/\\]/.test(p)) {
     return win32.resolve(p);
@@ -17,10 +17,11 @@ function resolveComparablePath(p) {
 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(/[/\\]/).filter((s) => s.length > 0);
+  if (/^[a-zA-Z]:/.test(spaPath)) return false;
+  if (spaPath === "." || spaPath === "./") return false;
+  const segments = spaPath.split(/[/\\]/).filter((s) => s.length > 0 && s !== ".");
   if (segments.some((s) => s === "..")) return false;
-  return true;
+  return segments.length > 0;
 }
 function assertResolvedPathUnderRoot(root, target) {
   const rootResolved = resolveComparablePath(root);
@@ -52,13 +53,25 @@ function assertRealPathUnderRoot(root, target) {
   }
   assertResolvedPathUnderRoot(rootReal, targetCheck);
 }
+function normalizePathForComparison(p) {
+  const resolved = resolveComparablePath(p);
+  return /^[a-zA-Z]:[/\\]/.test(resolved) ? resolved.toLowerCase() : resolved;
+}
+function relativePathUnderRoot(root, target) {
+  const rootResolved = normalizePathForComparison(root);
+  const targetResolved = normalizePathForComparison(target);
+  if (/^[a-zA-Z]:[/\\]/.test(rootResolved)) {
+    return win32.relative(rootResolved, targetResolved);
+  }
+  return relative(rootResolved, targetResolved);
+}
 function isResolvedPathUnderRoot(root, target) {
-  const rootResolved = resolveComparablePath(root);
-  const targetResolved = resolveComparablePath(target);
+  const rootResolved = normalizePathForComparison(root);
+  const targetResolved = normalizePathForComparison(target);
   if (targetResolved === rootResolved) return true;
-  const prefix = rootResolved.endsWith(sep) ? rootResolved : rootResolved + sep;
-  const win32Prefix = rootResolved.endsWith(win32.sep) ? rootResolved : rootResolved + win32.sep;
-  return targetResolved.startsWith(prefix) || targetResolved.startsWith(win32Prefix);
+  const rel = relativePathUnderRoot(root, target);
+  if (!rel) return true;
+  return !rel.startsWith("..") && !isAbsolute(rel);
 }
 
 // src/theme.ts
@@ -79,6 +92,70 @@ function themeToLxpackRuntime(input) {
 // src/validateDescriptor.ts
 var VALID_LAYOUTS = ["single-spa", "per-lesson-spa"];
 var VALID_THEME_PRESETS = ["default", "light", "dark", "brand"];
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseLessonDescriptor(raw) {
+  if (!isRecord(raw)) {
+    return { id: "", title: "" };
+  }
+  return {
+    id: typeof raw.id === "string" ? raw.id : "",
+    title: typeof raw.title === "string" ? raw.title : "",
+    spaPath: typeof raw.spaPath === "string" ? raw.spaPath : void 0
+  };
+}
+function parseAssessmentDescriptor(raw) {
+  if (!isRecord(raw)) {
+    return { checkId: "", question: "", choices: [], answer: "" };
+  }
+  return {
+    checkId: typeof raw.checkId === "string" ? raw.checkId : "",
+    question: typeof raw.question === "string" ? raw.question : "",
+    choices: Array.isArray(raw.choices) ? raw.choices.filter((c) => typeof c === "string") : [],
+    answer: typeof raw.answer === "string" ? raw.answer : "",
+    passingScore: typeof raw.passingScore === "number" ? raw.passingScore : void 0
+  };
+}
+function parseCourseDescriptorInput(input) {
+  if (!isRecord(input)) return null;
+  const trackingRaw = input.tracking;
+  let tracking;
+  if (isRecord(trackingRaw)) {
+    const completionRaw = trackingRaw.completion;
+    const xapiRaw = trackingRaw.xapi;
+    tracking = {
+      completion: isRecord(completionRaw) ? {
+        threshold: typeof completionRaw.threshold === "number" ? completionRaw.threshold : void 0
+      } : void 0,
+      xapi: isRecord(xapiRaw) ? {
+        activityIri: typeof xapiRaw.activityIri === "string" ? xapiRaw.activityIri : void 0
+      } : void 0
+    };
+  }
+  const themeRaw = input.theme;
+  let theme;
+  if (isRecord(themeRaw)) {
+    theme = {
+      preset: typeof themeRaw.preset === "string" ? themeRaw.preset : void 0
+    };
+    if (isRecord(themeRaw.theme)) {
+      theme.theme = themeRaw.theme;
+    }
+  }
+  return {
+    courseId: typeof input.courseId === "string" ? input.courseId : "",
+    title: typeof input.title === "string" ? input.title : "",
+    version: typeof input.version === "string" ? input.version : void 0,
+    layout: typeof input.layout === "string" ? input.layout : void 0,
+    lessons: Array.isArray(input.lessons) ? input.lessons.map(parseLessonDescriptor) : [],
+    assessments: Array.isArray(input.assessments) ? input.assessments.map(parseAssessmentDescriptor) : void 0,
+    theme,
+    tracking,
+    spaDistDir: typeof input.spaDistDir === "string" ? input.spaDistDir : void 0,
+    spaLessonId: typeof input.spaLessonId === "string" ? input.spaLessonId : void 0
+  };
+}
 function normalizeDescriptor(input) {
   const course = validateId(input.courseId, "courseId");
   if (!course.ok) throw new Error("normalizeDescriptor called with invalid courseId");
@@ -112,6 +189,31 @@ function normalizeDescriptor(input) {
   };
 }
 function validateDescriptor(input) {
+  const parsed = parseCourseDescriptorInput(input);
+  if (parsed === null) {
+    return { ok: false, issues: [{ path: "course", message: "must be an object" }] };
+  }
+  return validateDescriptorParsed(parsed);
+}
+function validateDescriptorForTarget(input, target) {
+  const result = validateDescriptor(input);
+  if (!result.ok || !target) return result;
+  if (target !== "xapi" && target !== "cmi5") return result;
+  const activityIri = result.descriptor.tracking?.xapi?.activityIri?.trim();
+  if (!activityIri) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: "course.tracking.xapi.activityIri",
+          message: "tracking.xapi.activityIri is required for xapi and cmi5 export targets"
+        }
+      ]
+    };
+  }
+  return result;
+}
+function validateDescriptorParsed(input) {
   const issues = [];
   const course = validateId(input.courseId, "courseId");
   if (!course.ok) issues.push(...course.issues.map((i) => ({ path: i.path, message: i.message })));
@@ -247,7 +349,7 @@ function validateDescriptor(input) {
 }
 
 // src/validateProjectPaths.ts
-import { isAbsolute, resolve as resolve2 } from "path";
+import { isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
 function validatePathField(value, fieldPath, projectRoot, issues) {
   if (!isSafeRelativeSpaPath(value)) {
     issues.push({
@@ -257,7 +359,7 @@ function validatePathField(value, fieldPath, projectRoot, issues) {
     return;
   }
   try {
-    assertResolvedPathUnderRoot(projectRoot, resolve2(projectRoot, value));
+    assertRealPathUnderRoot(projectRoot, resolve2(projectRoot, value));
   } catch {
     issues.push({
       path: fieldPath,
@@ -285,16 +387,16 @@ function resolveSafePackageOutputOverride(projectRoot, override) {
   if (!trimmed) {
     throw new Error("output override must be a non-empty path");
   }
-  if (isAbsolute(trimmed)) {
+  if (isAbsolute2(trimmed)) {
     const resolved2 = resolve2(trimmed);
-    assertResolvedPathUnderRoot(root, resolved2);
+    assertRealPathUnderRoot(root, resolved2);
     return resolved2;
   }
   if (!isSafeRelativeSpaPath(trimmed)) {
     throw new Error(`unsafe output path: ${override}`);
   }
   const resolved = resolve2(root, trimmed);
-  assertResolvedPathUnderRoot(root, resolved);
+  assertRealPathUnderRoot(root, resolved);
   return resolved;
 }
 
@@ -341,6 +443,18 @@ function extractAssessments(descriptor) {
 }
 
 // src/interchange.ts
+function mapDescriptorTracking(tracking) {
+  if (!tracking) return void 0;
+  const mapped = {};
+  if (tracking.completion?.threshold !== void 0) {
+    mapped.completion = { threshold: tracking.completion.threshold };
+  }
+  const activityIri = tracking.xapi?.activityIri?.trim();
+  if (activityIri) {
+    mapped.xapi = { activityIri };
+  }
+  return Object.keys(mapped).length > 0 ? mapped : void 0;
+}
 function resolveSpaLessons(descriptor) {
   const mapped = mapLessonkitIds(descriptor);
   if (descriptor.layout === "single-spa") {
@@ -378,7 +492,7 @@ function descriptorToInterchange(descriptor) {
       type: "spa",
       path: l.path
     })),
-    tracking: descriptor.tracking,
+    tracking: mapDescriptorTracking(descriptor.tracking),
     runtime: runtime ? {
       theme: runtime.theme,
       cssVariables: runtime.cssVariables
@@ -455,7 +569,7 @@ async function writeLxpackProject(options) {
   const descriptor = validation.descriptor;
   const outDir = resolve4(options.outDir);
   if (options.projectRoot) {
-    assertResolvedPathUnderRoot(resolve4(options.projectRoot), outDir);
+    assertRealPathUnderRoot(resolve4(options.projectRoot), outDir);
   }
   const spaDirs = await resolveSpaDirs({ ...options, descriptor });
   const interchange = descriptorToInterchange(descriptor);
@@ -487,14 +601,14 @@ import {
 } from "@lxpack/api";
 
 // src/packaging/validateInputs.ts
-import { join as join3, resolve as resolve5, win32 as win322 } from "path";
+import { isAbsolute as isAbsolute3, join as join3, resolve as resolve5, win32 as win322 } from "path";
 function validatePackageInputs(options) {
   const { target, output, outputBaseDir } = options;
   const outDir = resolve5(options.outDir);
   const projectRoot = options.projectRoot ? resolve5(options.projectRoot) : void 0;
   if (projectRoot) {
     try {
-      assertResolvedPathUnderRoot(projectRoot, outDir);
+      assertRealPathUnderRoot(projectRoot, outDir);
     } catch (err) {
       return {
         ok: false,
@@ -541,7 +655,7 @@ function validatePackageInputs(options) {
   if (projectRoot && output) {
     const resolvedOutput = resolve5(projectRoot, output);
     try {
-      assertResolvedPathUnderRoot(projectRoot, resolvedOutput);
+      assertRealPathUnderRoot(projectRoot, resolvedOutput);
     } catch (err) {
       return {
         ok: false,
@@ -570,17 +684,21 @@ function remapArtifactPaths(stagingRoot, outDir, artifactPath) {
   if (!isResolvedPathUnderRoot(stagingRoot, resolved)) {
     return artifactPath;
   }
-  const stagingResolved = resolveComparablePath(stagingRoot);
-  const relative2 = resolved === stagingResolved ? "" : resolved.slice(stagingResolved.length).replace(/^[/\\]/, "");
-  if (!relative2) return outDir;
+  const rel = relativePathUnderRoot(stagingRoot, resolved);
+  if (rel.startsWith("..") || isAbsolute3(rel)) {
+    return artifactPath;
+  }
+  if (!rel) return outDir;
   if (/^[a-zA-Z]:[/\\]/.test(outDir)) {
-    return win322.join(outDir, relative2.replace(/\//g, win322.sep));
+    return win322.join(outDir, rel.replace(/\//g, win322.sep));
   }
-  return join3(outDir, relative2);
+  return join3(outDir, rel);
 }
 
 // src/packaging/promote.ts
 import * as fsp from "fs/promises";
+import { randomUUID } from "crypto";
+import { dirname, join as join4 } from "path";
 async function pathExists(path) {
   try {
     await fsp.access(path);
@@ -599,22 +717,36 @@ async function renameOrCopy(from, to) {
     await fsp.rm(from, { recursive: true, force: true });
   }
 }
+async function assertNoLegacyPromoteArtifacts(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) {
+    throw new Error(
+      `[lessonkit/lxpack] cannot promote: remove stale packaging artifacts from a previous failed run: ${stale.join(", ")}`
+    );
+  }
+}
 async function promoteStagingToOutDir(stagingDir, outDir) {
-  const tmpPromote = `${outDir}.tmp-promote`;
-  const backup = `${outDir}.bak`;
+  await assertNoLegacyPromoteArtifacts(outDir);
+  const parent = dirname(outDir);
+  const tmpPromote = await fsp.mkdtemp(join4(parent, ".lk-promote-"));
   await renameOrCopy(stagingDir, tmpPromote);
   const hadOutDir = await pathExists(outDir);
-  if (hadOutDir) {
+  const backup = hadOutDir ? await fsp.mkdtemp(join4(parent, ".lk-backup-")) : void 0;
+  if (hadOutDir && backup) {
     await renameOrCopy(outDir, backup);
   }
   try {
     await renameOrCopy(tmpPromote, outDir);
   } catch (promoteError) {
-    if (hadOutDir) {
+    if (hadOutDir && backup) {
       try {
         await renameOrCopy(backup, outDir);
       } catch (restoreError) {
-        const failedPromote2 = `${outDir}.failed-promote-${Date.now()}`;
+        const failedPromote2 = join4(parent, `.lk-failed-promote-${randomUUID()}`);
         try {
           await renameOrCopy(tmpPromote, failedPromote2);
         } catch {
@@ -638,7 +770,7 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
       }
       throw promoteError;
     }
-    const failedPromote = `${outDir}.failed-promote-${Date.now()}`;
+    const failedPromote = join4(parent, `.lk-failed-promote-${randomUUID()}`);
     try {
       await renameOrCopy(tmpPromote, failedPromote);
     } catch {
@@ -646,19 +778,19 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
     }
     throw promoteError;
   }
-  if (hadOutDir) {
+  if (backup) {
     await fsp.rm(backup, { recursive: true, force: true }).catch(() => void 0);
   }
 }
 
 // src/packaging/staging.ts
 import * as fsp2 from "fs/promises";
-import { dirname, join as join4 } from "path";
+import { dirname as dirname2, join as join5 } 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(join4(tmpdir(), "lessonkit-lxpack-"));
+  const stagingDir = await fsp2.mkdtemp(join5(tmpdir(), "lessonkit-lxpack-"));
   try {
     let spaDirs;
     try {
@@ -677,8 +809,8 @@ async function buildStagingPackage(options) {
     }
     const interchange = descriptorToInterchange(descriptor);
     const outputBase = outputBaseDir ?? ".lxpack/out";
-    await fsp2.mkdir(join4(stagingDir, outputBase), { recursive: true });
-    const defaultOutput = output ?? (dir ? join4(outputBase, target) : join4(outputBase, `course-${target}.zip`));
+    await fsp2.mkdir(join5(stagingDir, outputBase), { recursive: true });
+    const defaultOutput = output ?? (dir ? join5(outputBase, target) : join5(outputBase, `course-${target}.zip`));
     const build = await packageLessonkit({
       interchange,
       spaDirs,
@@ -715,7 +847,7 @@ async function buildStagingPackage(options) {
   }
 }
 async function ensureOutDirParent(outDir) {
-  await fsp2.mkdir(dirname(outDir), { recursive: true });
+  await fsp2.mkdir(dirname2(outDir), { recursive: true });
 }
 
 // src/packageCourse.ts
@@ -726,14 +858,15 @@ async function validateLessonkitProject(options) {
   });
 }
 async function buildLessonkitProject(options) {
-  return buildCourse({
+  const buildOptions = {
     courseDir: resolve6(options.courseDir),
     target: options.target,
     output: options.output,
     dir: options.dir,
     outputBaseDir: options.outputBaseDir,
     assessments: options.assessments
-  });
+  };
+  return buildCourse(buildOptions);
 }
 async function packageLessonkitCourse(options) {
   const { target, output, dir, outputBaseDir, ...writeOpts } = options;
@@ -753,11 +886,11 @@ async function packageLessonkitCourse(options) {
     };
   }
   const outDir = inputValidation.outDir;
-  const descriptorValidation = validateDescriptor(writeOpts.descriptor);
+  const descriptorValidation = validateDescriptorForTarget(writeOpts.descriptor, target);
   if (!descriptorValidation.ok) {
     return {
       ok: false,
-      courseDir: outDir,
+      courseDir: resolve6(writeOpts.outDir),
       target,
       issues: descriptorValidation.issues.map((i) => ({
         path: i.path,
@@ -766,22 +899,6 @@ async function packageLessonkitCourse(options) {
     };
   }
   const descriptor = descriptorValidation.descriptor;
-  if (target === "xapi" || target === "cmi5") {
-    const activityIri = descriptor.tracking?.xapi?.activityIri?.trim();
-    if (!activityIri) {
-      return {
-        ok: false,
-        courseDir: outDir,
-        target,
-        issues: [
-          {
-            path: "course.tracking.xapi.activityIri",
-            message: "tracking.xapi.activityIri is required for xapi and cmi5 export targets"
-          }
-        ]
-      };
-    }
-  }
   const staged = await buildStagingPackage({
     ...writeOpts,
     descriptor,
@@ -875,14 +992,19 @@ function parseLessonkitManifest(raw, label = "lessonkit.json", projectRoot) {
   }
   const config = raw;
   const issues = [];
-  if (config.schemaVersion !== 1) {
+  let schemaVersion = config.schemaVersion;
+  if (schemaVersion === "1") {
+    schemaVersion = 1;
+  }
+  if (schemaVersion !== 1) {
     issues.push({
       path: "schemaVersion",
       message: `must be 1 (got ${String(config.schemaVersion)})`
     });
   }
-  const name = config.name;
-  if (typeof name !== "string" || !name.trim()) {
+  const nameRaw = config.name;
+  const name = typeof nameRaw === "string" ? nameRaw.trim() : "";
+  if (!name) {
     issues.push({ path: "name", message: "must be a non-empty string" });
   }
   const courseRaw = config.course;
@@ -1000,6 +1122,7 @@ export {
   telemetryEventToLessonkit,
   themeToLxpackRuntime,
   validateDescriptor,
+  validateDescriptorForTarget,
   validateLessonkitProject,
   validatePackageInputs,
   validateProjectPaths,

package/lessonkit-manifest.v1.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lessonkit.dev/schemas/lessonkit-manifest.v1.json",
+  "title": "LessonkitManifestV1",
+  "description": "Root lessonkit.json project manifest (schemaVersion 1)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "name", "course", "paths"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "name": { "type": "string", "minLength": 1 },
+    "course": { "$ref": "#/$defs/LessonkitCourseDescriptor" },
+    "paths": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["spaDistDir", "lxpackOutDir", "outputBaseDir"],
+      "properties": {
+        "spaDistDir": { "type": "string", "minLength": 1 },
+        "lxpackOutDir": { "type": "string", "minLength": 1 },
+        "outputBaseDir": { "type": "string", "minLength": 1 }
+      }
+    }
+  },
+  "$defs": {
+    "LessonkitId": {
+      "type": "string",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$",
+      "maxLength": 64
+    },
+    "LessonkitCourseDescriptor": {
+      "type": "object",
+      "required": ["courseId", "title", "layout", "lessons"],
+      "properties": {
+        "courseId": { "$ref": "#/$defs/LessonkitId" },
+        "title": { "type": "string", "minLength": 1 },
+        "version": { "type": "string" },
+        "layout": { "enum": ["single-spa", "per-lesson-spa"] },
+        "lessons": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/LessonDescriptor" }
+        },
+        "assessments": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/AssessmentDescriptor" }
+        },
+        "theme": {
+          "type": "object",
+          "properties": {
+            "preset": { "enum": ["default", "light", "dark", "brand"] },
+            "theme": { "type": "object" }
+          }
+        },
+        "tracking": {
+          "type": "object",
+          "properties": {
+            "completion": {
+              "type": "object",
+              "properties": {
+                "threshold": { "type": "number", "minimum": 0, "maximum": 1 }
+              }
+            },
+            "xapi": {
+              "type": "object",
+              "properties": {
+                "activityIri": { "type": "string", "minLength": 1 }
+              }
+            }
+          }
+        },
+        "spaDistDir": { "type": "string", "minLength": 1 },
+        "spaLessonId": { "$ref": "#/$defs/LessonkitId" }
+      }
+    },
+    "LessonDescriptor": {
+      "type": "object",
+      "required": ["id", "title"],
+      "properties": {
+        "id": { "$ref": "#/$defs/LessonkitId" },
+        "title": { "type": "string", "minLength": 1 },
+        "spaPath": { "type": "string", "minLength": 1 }
+      }
+    },
+    "AssessmentDescriptor": {
+      "type": "object",
+      "required": ["checkId", "question", "choices", "answer"],
+      "properties": {
+        "checkId": { "$ref": "#/$defs/LessonkitId" },
+        "question": { "type": "string", "minLength": 1 },
+        "choices": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "answer": { "type": "string", "minLength": 1 },
+        "passingScore": { "type": "number", "exclusiveMinimum": 0 }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/lxpack",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "private": false,
   "description": "LXPack export adapter for LessonKit courses (SCORM, standalone, xAPI, cmi5).",
   "license": "Apache-2.0",
@@ -38,10 +38,12 @@
       "types": "./dist/bridge.d.ts",
       "import": "./dist/bridge.js",
       "require": "./dist/bridge.cjs"
-    }
+    },
+    "./lessonkit-manifest.v1.json": "./lessonkit-manifest.v1.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "lessonkit-manifest.v1.json"
   ],
   "scripts": {
     "build": "tsup src/index.ts src/bridge.ts --format esm,cjs --dts",
@@ -53,8 +55,8 @@
     "lint": "echo \"(no lint configured yet)\""
   },
   "dependencies": {
-    "@lessonkit/core": "1.0.0",
-    "@lessonkit/themes": "1.0.0",
+    "@lessonkit/core": "1.0.2",
+    "@lessonkit/themes": "1.0.2",
     "@lxpack/api": "^0.6.2",
     "@lxpack/spa-bridge": "^0.6.2",
     "@lxpack/tracking-schema": "^0.6.2",
@@ -64,6 +66,6 @@
     "@types/node": "^22.13.10",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.8"
   }
 }