@lessonkit/lxpack 1.5.0 → 1.7.0

package/dist/index.d.cts

@@ -53,8 +53,31 @@ type FindMultipleHotspotsAssessmentDescriptor = {
     correctTargetIds: string[];
     passingScore?: number;
 };
+type SortParagraphsAssessmentDescriptor = {
+    kind: "sortParagraphs";
+    checkId: CheckId;
+    question: string;
+    paragraphs: string[];
+    correctOrder: number[];
+    passingScore?: number;
+};
+type GuessTheAnswerAssessmentDescriptor = {
+    kind: "guessTheAnswer";
+    checkId: CheckId;
+    question: string;
+    answer: string;
+    passingScore?: number;
+};
+type MultimediaChoiceAssessmentDescriptor = {
+    kind: "multimediaChoice";
+    checkId: CheckId;
+    question: string;
+    choices: string[];
+    answer: string;
+    passingScore?: number;
+};
 /** Discriminated assessment entries in lessonkit.json (defaults to MCQ when kind omitted). */
-type AssessmentDescriptor = McqAssessmentDescriptor | TrueFalseAssessmentDescriptor | FillInBlanksAssessmentDescriptor | FindHotspotAssessmentDescriptor | FindMultipleHotspotsAssessmentDescriptor;
+type AssessmentDescriptor = McqAssessmentDescriptor | TrueFalseAssessmentDescriptor | FillInBlanksAssessmentDescriptor | FindHotspotAssessmentDescriptor | FindMultipleHotspotsAssessmentDescriptor | SortParagraphsAssessmentDescriptor | GuessTheAnswerAssessmentDescriptor | MultimediaChoiceAssessmentDescriptor;
 type LessonkitCourseDescriptor = {
     courseId: CourseId;
     title: string;
@@ -127,6 +150,8 @@ type ProjectPathsInput = {
     lxpackOutDir?: string;
     outputBaseDir?: string;
 };
+/** Validate lessonkit.json `name` for safe default export/archive paths. */
+declare function validateManifestName(name: string): string | null;
 /** Validate lessonkit.json paths.* entries stay under projectRoot. */
 declare function validateProjectPaths(projectRoot: string, paths: ProjectPathsInput): DescriptorValidationIssue[];
 /**
@@ -155,15 +180,30 @@ type SpaLessonEntry = {
     path: string;
 };
 declare function resolveSpaLessons(descriptor: LessonkitCourseDescriptor): SpaLessonEntry[];
+/**
+ * Convert a `lessonkit.json` course descriptor to portable interchange JSON for `.lkcourse`.
+ *
+ * @example
+ * ```ts
+ * import { descriptorToInterchange } from "@lessonkit/lxpack";
+ *
+ * const interchange = descriptorToInterchange(manifest.course);
+ * ```
+ */
 declare function descriptorToInterchange(descriptor: LessonkitCourseDescriptor): LessonkitInterchangeV1;
 
 type LxpackInjectedAssessment = {
     id: string;
     title?: string;
     passingScore: number;
+    maxAttempts?: number;
+    shuffleChoices?: boolean;
+    showFeedback?: "never" | "immediate" | "end";
     questions: Array<{
         id: string;
         prompt: string;
+        explanation?: string;
+        selectionMode?: "single" | "multiple";
         choices: Array<{
             id: string;
             text: string;
@@ -199,6 +239,18 @@ type WriteLxpackProjectResult = {
 };
 /**
  * Materialize an LXPack project tree from a LessonKit descriptor (delegates to LXPack 0.6+).
+ *
+ * @example
+ * ```ts
+ * import { writeLxpackProject } from "@lessonkit/lxpack";
+ *
+ * await writeLxpackProject({
+ *   descriptor: courseFromLessonkitJson,
+ *   outDir: ".lxpack/course",
+ *   spaDistDir: "dist",
+ *   projectRoot: process.cwd(),
+ * });
+ * ```
  */
 declare function writeLxpackProject(options: WriteLxpackProjectOptions): Promise<WriteLxpackProjectResult>;
 
@@ -225,6 +277,9 @@ type BuildStagingPackageResult = {
     }>;
     outputPath?: string;
     outputDir?: string;
+    /** Absolute project-root output path when `output` was explicitly requested. */
+    requestedOutputPath?: string;
+    requestedOutputDir?: string;
 } | {
     ok: false;
     stagingDir: string;
@@ -260,6 +315,8 @@ type PackageLessonkitCourseOptions = WriteLxpackProjectOptions & {
     outputBaseDir?: string;
     /** Treat React parity warnings as packaging errors. */
     strictParity?: boolean;
+    /** Treat LXPack build warnings as packaging errors. */
+    strictBuild?: boolean;
 };
 type PackageLessonkitCourseResult = {
     ok: true;
@@ -282,12 +339,43 @@ type PackageLessonkitCourseResult = {
         severity?: string;
     }>;
 };
+/**
+ * Validate an on-disk LXPack course directory before packaging.
+ *
+ * @example
+ * ```ts
+ * import { validateLessonkitProject } from "@lessonkit/lxpack";
+ *
+ * const result = await validateLessonkitProject({
+ *   courseDir: ".lxpack/course",
+ *   target: "scorm12",
+ * });
+ * ```
+ */
 declare function validateLessonkitProject(options: ValidateLessonkitProjectOptions): Promise<ValidateCourseResult>;
 declare function buildLessonkitProject(options: BuildLessonkitProjectOptions): Promise<BuildCourseResult>;
 
 /**
  * Package a built SPA into SCORM, xAPI, cmi5, or standalone LMS artifacts.
  * Prefer `lessonkit package --target …` in course projects; call directly for custom pipelines.
+ *
+ * @example
+ * ```ts
+ * import { packageLessonkitCourse } from "@lessonkit/lxpack";
+ *
+ * const result = await packageLessonkitCourse({
+ *   descriptor: manifest.course,
+ *   outDir: ".lxpack/course",
+ *   spaDistDir: "dist",
+ *   projectRoot: process.cwd(),
+ *   target: "scorm12",
+ *   strictBuild: true,
+ * });
+ * if (!result.ok) console.error(result.issues);
+ * ```
+ *
+ * @remarks Returns `{ ok: false, issues }` (does not throw) for manifest parity failures,
+ * missing `dist/`, LXPack validation errors, or `strictBuild` / `strictParity` warnings.
  */
 declare function packageLessonkitCourse(options: PackageLessonkitCourseOptions): Promise<PackageLessonkitCourseResult>;
 
@@ -311,6 +399,11 @@ declare function validatePackageInputs(options: Pick<PackageLessonkitCourseOptio
 }): ValidatePackageInputsResult;
 declare function remapArtifactPaths(stagingRoot: string, outDir: string, artifactPath: string | undefined): string | undefined;
 
+/**
+ * Reject symlinks and paths escaping dist roots before packaging LMS artifacts.
+ */
+declare function assertSpaDistContentsSafe(spaDirs: Record<string, string>, projectRoot?: string): Promise<void>;
+
 type LessonkitManifestPaths = {
     spaDistDir: string;
     lxpackOutDir: string;
@@ -340,4 +433,121 @@ 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 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, escapeShellText, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };
+type LkcourseEnvelopeV1 = {
+    format: "lkcourse";
+    schemaVersion: 1;
+    lessonkitVersion: string;
+    exportedAt: string;
+    sourceManifest: LessonkitManifest;
+    entries: string[];
+};
+type BlockTreeNodeV1 = {
+    type: string;
+    rawTag?: string;
+    courseId?: string;
+    lessonId?: string;
+    checkId?: string;
+    blockId?: string;
+    nodeId?: string;
+    children?: BlockTreeNodeV1[];
+};
+type BlockTreeV1 = {
+    schemaVersion: 1;
+    sources: string[];
+    blocks: BlockTreeNodeV1[];
+};
+type LkcourseValidationIssue = {
+    path: string;
+    message: string;
+};
+type ExportLkcourseOptions = {
+    projectRoot: string;
+    manifest: LessonkitManifest;
+    outPath?: string;
+    includeBlockTree?: boolean;
+    lessonkitVersion?: string;
+};
+type ExportLkcourseResult = {
+    ok: true;
+    archivePath: string;
+    fileCount: number;
+    includeBlockTree: boolean;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+type ValidateLkcourseResult = {
+    ok: true;
+    envelope: LkcourseEnvelopeV1;
+    interchange: LessonkitInterchangeV1;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+type ImportLkcourseOptions = {
+    archivePath: string;
+    targetDir: string;
+};
+type ImportLkcourseResult = {
+    ok: true;
+    targetDir: string;
+    manifest: LessonkitManifest;
+    interchange: LessonkitInterchangeV1;
+    fileCount: number;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+type ExtractBlockTreeOptions = {
+    projectRoot: string;
+    blockTypes?: string[];
+    appSources?: string[];
+};
+
+type ParseEnvelopeResult = {
+    ok: true;
+    envelope: LkcourseEnvelopeV1;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+declare function parseLkcourseEnvelope(raw: unknown, label?: string): ParseEnvelopeResult;
+
+declare function extractBlockTree(options: ExtractBlockTreeOptions): BlockTreeV1;
+
+/**
+ * Build a portable `.lkcourse` zip (manifest envelope + interchange + dist).
+ * Prefer `lessonkit export` in course projects.
+ *
+ * @example
+ * ```ts
+ * import { exportLkcourse } from "@lessonkit/lxpack";
+ *
+ * const result = await exportLkcourse({
+ *   projectRoot: "/path/to/course",
+ *   manifest: parsedLessonkitJson,
+ *   archivePath: "handoff.lkcourse",
+ * });
+ * ```
+ */
+declare function exportLkcourse(options: ExportLkcourseOptions): Promise<ExportLkcourseResult>;
+
+declare function validateLkcourseArchiveEntries(entries: Map<string, Uint8Array>, _archiveLabel: string): ValidateLkcourseResult;
+declare function validateLkcourse(archivePath: string): ValidateLkcourseResult;
+
+/**
+ * Extract a `.lkcourse` archive into a project directory (manifest + dist tree).
+ *
+ * @example
+ * ```ts
+ * import { importLkcourse } from "@lessonkit/lxpack";
+ *
+ * const result = await importLkcourse({
+ *   archivePath: "handoff.lkcourse",
+ *   targetDir: "/path/to/dest",
+ * });
+ * ```
+ */
+declare function importLkcourse(options: ImportLkcourseOptions): Promise<ImportLkcourseResult>;
+
+export { type AssessmentDescriptor, type BlockTreeNodeV1, type BlockTreeV1, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type ExportLkcourseOptions, type ExportLkcourseResult, type ExtractBlockTreeOptions, type FillInBlanksAssessmentDescriptor, type ImportLkcourseOptions, type ImportLkcourseResult, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitExportTarget, type LessonkitManifest, type LessonkitManifestPaths, type LkcourseEnvelopeV1, type LkcourseValidationIssue, 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 ValidateLkcourseResult, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assertSpaDistContentsSafe, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, escapeShellText, exportLkcourse, extractAssessments, extractBlockTree, importLkcourse, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, parseLkcourseEnvelope, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validateLkcourse, validateLkcourseArchiveEntries, validateManifestName, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };

package/dist/index.d.ts

@@ -53,8 +53,31 @@ type FindMultipleHotspotsAssessmentDescriptor = {
     correctTargetIds: string[];
     passingScore?: number;
 };
+type SortParagraphsAssessmentDescriptor = {
+    kind: "sortParagraphs";
+    checkId: CheckId;
+    question: string;
+    paragraphs: string[];
+    correctOrder: number[];
+    passingScore?: number;
+};
+type GuessTheAnswerAssessmentDescriptor = {
+    kind: "guessTheAnswer";
+    checkId: CheckId;
+    question: string;
+    answer: string;
+    passingScore?: number;
+};
+type MultimediaChoiceAssessmentDescriptor = {
+    kind: "multimediaChoice";
+    checkId: CheckId;
+    question: string;
+    choices: string[];
+    answer: string;
+    passingScore?: number;
+};
 /** Discriminated assessment entries in lessonkit.json (defaults to MCQ when kind omitted). */
-type AssessmentDescriptor = McqAssessmentDescriptor | TrueFalseAssessmentDescriptor | FillInBlanksAssessmentDescriptor | FindHotspotAssessmentDescriptor | FindMultipleHotspotsAssessmentDescriptor;
+type AssessmentDescriptor = McqAssessmentDescriptor | TrueFalseAssessmentDescriptor | FillInBlanksAssessmentDescriptor | FindHotspotAssessmentDescriptor | FindMultipleHotspotsAssessmentDescriptor | SortParagraphsAssessmentDescriptor | GuessTheAnswerAssessmentDescriptor | MultimediaChoiceAssessmentDescriptor;
 type LessonkitCourseDescriptor = {
     courseId: CourseId;
     title: string;
@@ -127,6 +150,8 @@ type ProjectPathsInput = {
     lxpackOutDir?: string;
     outputBaseDir?: string;
 };
+/** Validate lessonkit.json `name` for safe default export/archive paths. */
+declare function validateManifestName(name: string): string | null;
 /** Validate lessonkit.json paths.* entries stay under projectRoot. */
 declare function validateProjectPaths(projectRoot: string, paths: ProjectPathsInput): DescriptorValidationIssue[];
 /**
@@ -155,15 +180,30 @@ type SpaLessonEntry = {
     path: string;
 };
 declare function resolveSpaLessons(descriptor: LessonkitCourseDescriptor): SpaLessonEntry[];
+/**
+ * Convert a `lessonkit.json` course descriptor to portable interchange JSON for `.lkcourse`.
+ *
+ * @example
+ * ```ts
+ * import { descriptorToInterchange } from "@lessonkit/lxpack";
+ *
+ * const interchange = descriptorToInterchange(manifest.course);
+ * ```
+ */
 declare function descriptorToInterchange(descriptor: LessonkitCourseDescriptor): LessonkitInterchangeV1;
 
 type LxpackInjectedAssessment = {
     id: string;
     title?: string;
     passingScore: number;
+    maxAttempts?: number;
+    shuffleChoices?: boolean;
+    showFeedback?: "never" | "immediate" | "end";
     questions: Array<{
         id: string;
         prompt: string;
+        explanation?: string;
+        selectionMode?: "single" | "multiple";
         choices: Array<{
             id: string;
             text: string;
@@ -199,6 +239,18 @@ type WriteLxpackProjectResult = {
 };
 /**
  * Materialize an LXPack project tree from a LessonKit descriptor (delegates to LXPack 0.6+).
+ *
+ * @example
+ * ```ts
+ * import { writeLxpackProject } from "@lessonkit/lxpack";
+ *
+ * await writeLxpackProject({
+ *   descriptor: courseFromLessonkitJson,
+ *   outDir: ".lxpack/course",
+ *   spaDistDir: "dist",
+ *   projectRoot: process.cwd(),
+ * });
+ * ```
  */
 declare function writeLxpackProject(options: WriteLxpackProjectOptions): Promise<WriteLxpackProjectResult>;
 
@@ -225,6 +277,9 @@ type BuildStagingPackageResult = {
     }>;
     outputPath?: string;
     outputDir?: string;
+    /** Absolute project-root output path when `output` was explicitly requested. */
+    requestedOutputPath?: string;
+    requestedOutputDir?: string;
 } | {
     ok: false;
     stagingDir: string;
@@ -260,6 +315,8 @@ type PackageLessonkitCourseOptions = WriteLxpackProjectOptions & {
     outputBaseDir?: string;
     /** Treat React parity warnings as packaging errors. */
     strictParity?: boolean;
+    /** Treat LXPack build warnings as packaging errors. */
+    strictBuild?: boolean;
 };
 type PackageLessonkitCourseResult = {
     ok: true;
@@ -282,12 +339,43 @@ type PackageLessonkitCourseResult = {
         severity?: string;
     }>;
 };
+/**
+ * Validate an on-disk LXPack course directory before packaging.
+ *
+ * @example
+ * ```ts
+ * import { validateLessonkitProject } from "@lessonkit/lxpack";
+ *
+ * const result = await validateLessonkitProject({
+ *   courseDir: ".lxpack/course",
+ *   target: "scorm12",
+ * });
+ * ```
+ */
 declare function validateLessonkitProject(options: ValidateLessonkitProjectOptions): Promise<ValidateCourseResult>;
 declare function buildLessonkitProject(options: BuildLessonkitProjectOptions): Promise<BuildCourseResult>;
 
 /**
  * Package a built SPA into SCORM, xAPI, cmi5, or standalone LMS artifacts.
  * Prefer `lessonkit package --target …` in course projects; call directly for custom pipelines.
+ *
+ * @example
+ * ```ts
+ * import { packageLessonkitCourse } from "@lessonkit/lxpack";
+ *
+ * const result = await packageLessonkitCourse({
+ *   descriptor: manifest.course,
+ *   outDir: ".lxpack/course",
+ *   spaDistDir: "dist",
+ *   projectRoot: process.cwd(),
+ *   target: "scorm12",
+ *   strictBuild: true,
+ * });
+ * if (!result.ok) console.error(result.issues);
+ * ```
+ *
+ * @remarks Returns `{ ok: false, issues }` (does not throw) for manifest parity failures,
+ * missing `dist/`, LXPack validation errors, or `strictBuild` / `strictParity` warnings.
  */
 declare function packageLessonkitCourse(options: PackageLessonkitCourseOptions): Promise<PackageLessonkitCourseResult>;
 
@@ -311,6 +399,11 @@ declare function validatePackageInputs(options: Pick<PackageLessonkitCourseOptio
 }): ValidatePackageInputsResult;
 declare function remapArtifactPaths(stagingRoot: string, outDir: string, artifactPath: string | undefined): string | undefined;
 
+/**
+ * Reject symlinks and paths escaping dist roots before packaging LMS artifacts.
+ */
+declare function assertSpaDistContentsSafe(spaDirs: Record<string, string>, projectRoot?: string): Promise<void>;
+
 type LessonkitManifestPaths = {
     spaDistDir: string;
     lxpackOutDir: string;
@@ -340,4 +433,121 @@ 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 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, escapeShellText, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };
+type LkcourseEnvelopeV1 = {
+    format: "lkcourse";
+    schemaVersion: 1;
+    lessonkitVersion: string;
+    exportedAt: string;
+    sourceManifest: LessonkitManifest;
+    entries: string[];
+};
+type BlockTreeNodeV1 = {
+    type: string;
+    rawTag?: string;
+    courseId?: string;
+    lessonId?: string;
+    checkId?: string;
+    blockId?: string;
+    nodeId?: string;
+    children?: BlockTreeNodeV1[];
+};
+type BlockTreeV1 = {
+    schemaVersion: 1;
+    sources: string[];
+    blocks: BlockTreeNodeV1[];
+};
+type LkcourseValidationIssue = {
+    path: string;
+    message: string;
+};
+type ExportLkcourseOptions = {
+    projectRoot: string;
+    manifest: LessonkitManifest;
+    outPath?: string;
+    includeBlockTree?: boolean;
+    lessonkitVersion?: string;
+};
+type ExportLkcourseResult = {
+    ok: true;
+    archivePath: string;
+    fileCount: number;
+    includeBlockTree: boolean;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+type ValidateLkcourseResult = {
+    ok: true;
+    envelope: LkcourseEnvelopeV1;
+    interchange: LessonkitInterchangeV1;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+type ImportLkcourseOptions = {
+    archivePath: string;
+    targetDir: string;
+};
+type ImportLkcourseResult = {
+    ok: true;
+    targetDir: string;
+    manifest: LessonkitManifest;
+    interchange: LessonkitInterchangeV1;
+    fileCount: number;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+type ExtractBlockTreeOptions = {
+    projectRoot: string;
+    blockTypes?: string[];
+    appSources?: string[];
+};
+
+type ParseEnvelopeResult = {
+    ok: true;
+    envelope: LkcourseEnvelopeV1;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+declare function parseLkcourseEnvelope(raw: unknown, label?: string): ParseEnvelopeResult;
+
+declare function extractBlockTree(options: ExtractBlockTreeOptions): BlockTreeV1;
+
+/**
+ * Build a portable `.lkcourse` zip (manifest envelope + interchange + dist).
+ * Prefer `lessonkit export` in course projects.
+ *
+ * @example
+ * ```ts
+ * import { exportLkcourse } from "@lessonkit/lxpack";
+ *
+ * const result = await exportLkcourse({
+ *   projectRoot: "/path/to/course",
+ *   manifest: parsedLessonkitJson,
+ *   archivePath: "handoff.lkcourse",
+ * });
+ * ```
+ */
+declare function exportLkcourse(options: ExportLkcourseOptions): Promise<ExportLkcourseResult>;
+
+declare function validateLkcourseArchiveEntries(entries: Map<string, Uint8Array>, _archiveLabel: string): ValidateLkcourseResult;
+declare function validateLkcourse(archivePath: string): ValidateLkcourseResult;
+
+/**
+ * Extract a `.lkcourse` archive into a project directory (manifest + dist tree).
+ *
+ * @example
+ * ```ts
+ * import { importLkcourse } from "@lessonkit/lxpack";
+ *
+ * const result = await importLkcourse({
+ *   archivePath: "handoff.lkcourse",
+ *   targetDir: "/path/to/dest",
+ * });
+ * ```
+ */
+declare function importLkcourse(options: ImportLkcourseOptions): Promise<ImportLkcourseResult>;
+
+export { type AssessmentDescriptor, type BlockTreeNodeV1, type BlockTreeV1, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type ExportLkcourseOptions, type ExportLkcourseResult, type ExtractBlockTreeOptions, type FillInBlanksAssessmentDescriptor, type ImportLkcourseOptions, type ImportLkcourseResult, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitExportTarget, type LessonkitManifest, type LessonkitManifestPaths, type LkcourseEnvelopeV1, type LkcourseValidationIssue, 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 ValidateLkcourseResult, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assertSpaDistContentsSafe, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, escapeShellText, exportLkcourse, extractAssessments, extractBlockTree, importLkcourse, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, parseLkcourseEnvelope, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validateLkcourse, validateLkcourseArchiveEntries, validateManifestName, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };