@lessonkit/lxpack 1.4.0 → 1.6.0

package/dist/index.d.cts

@@ -6,7 +6,7 @@ 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.cjs';
+export { t as telemetryEventToLessonkit } from './telemetry-0fIWoomS.cjs';
 
 type SpaLayout = "single-spa" | "per-lesson-spa";
 type LessonDescriptor = {
@@ -155,6 +155,16 @@ 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 = {
@@ -171,6 +181,8 @@ type LxpackInjectedAssessment = {
         }>;
     }>;
 };
+/** Escape text embedded into LMS shell / SCORM interchange payloads. */
+declare function escapeShellText(text: string): string;
 declare function assessmentDescriptorToLxpack(assessment: AssessmentDescriptor): LxpackInjectedAssessment | null;
 declare function extractAssessments(descriptor: LessonkitCourseDescriptor): LxpackInjectedAssessment[];
 
@@ -187,8 +199,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;
+    /** Project root used to resolve relative SPA paths and confine output directories. */
+    projectRoot: string;
 };
 type WriteLxpackProjectResult = {
     outDir: string;
@@ -197,10 +209,28 @@ 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>;
 
-declare function promoteStagingToOutDir(stagingDir: string, outDir: string): Promise<void>;
+type PromoteStagingOptions = {
+    /** Relative path under `outDir` where LMS artifacts live (default `.lxpack/out`). */
+    outputBaseDir?: string;
+    /** When set, re-validates `outDir` is under the project root immediately before promote. */
+    projectRoot?: string;
+};
+declare function promoteStagingToOutDir(stagingDir: string, outDir: string, options?: PromoteStagingOptions): Promise<void>;
 
 type BuildStagingPackageOptions = WriteLxpackProjectOptions & {
     descriptor: LessonkitCourseDescriptor;
@@ -250,6 +280,10 @@ type PackageLessonkitCourseOptions = WriteLxpackProjectOptions & {
     output?: string;
     dir?: boolean;
     outputBaseDir?: string;
+    /** Treat React parity warnings as packaging errors. */
+    strictParity?: boolean;
+    /** Treat LXPack build warnings as packaging errors. */
+    strictBuild?: boolean;
 };
 type PackageLessonkitCourseResult = {
     ok: true;
@@ -275,6 +309,25 @@ type PackageLessonkitCourseResult = {
 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);
+ * ```
+ */
 declare function packageLessonkitCourse(options: PackageLessonkitCourseOptions): Promise<PackageLessonkitCourseResult>;
 
 type PackageValidationIssue = {
@@ -297,6 +350,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;
@@ -319,7 +377,128 @@ type ParseManifestResult = {
     ok: false;
     issues: ManifestParseIssue[];
 };
+/**
+ * Parse and validate a project-root `lessonkit.json` manifest (`schemaVersion: 1`).
+ * Pass `projectRoot` for path containment checks equivalent to the CLI.
+ */
 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, 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, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };

package/dist/index.d.ts

@@ -6,7 +6,7 @@ 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';
+export { t as telemetryEventToLessonkit } from './telemetry-0fIWoomS.js';
 
 type SpaLayout = "single-spa" | "per-lesson-spa";
 type LessonDescriptor = {
@@ -155,6 +155,16 @@ 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 = {
@@ -171,6 +181,8 @@ type LxpackInjectedAssessment = {
         }>;
     }>;
 };
+/** Escape text embedded into LMS shell / SCORM interchange payloads. */
+declare function escapeShellText(text: string): string;
 declare function assessmentDescriptorToLxpack(assessment: AssessmentDescriptor): LxpackInjectedAssessment | null;
 declare function extractAssessments(descriptor: LessonkitCourseDescriptor): LxpackInjectedAssessment[];
 
@@ -187,8 +199,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;
+    /** Project root used to resolve relative SPA paths and confine output directories. */
+    projectRoot: string;
 };
 type WriteLxpackProjectResult = {
     outDir: string;
@@ -197,10 +209,28 @@ 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>;
 
-declare function promoteStagingToOutDir(stagingDir: string, outDir: string): Promise<void>;
+type PromoteStagingOptions = {
+    /** Relative path under `outDir` where LMS artifacts live (default `.lxpack/out`). */
+    outputBaseDir?: string;
+    /** When set, re-validates `outDir` is under the project root immediately before promote. */
+    projectRoot?: string;
+};
+declare function promoteStagingToOutDir(stagingDir: string, outDir: string, options?: PromoteStagingOptions): Promise<void>;
 
 type BuildStagingPackageOptions = WriteLxpackProjectOptions & {
     descriptor: LessonkitCourseDescriptor;
@@ -250,6 +280,10 @@ type PackageLessonkitCourseOptions = WriteLxpackProjectOptions & {
     output?: string;
     dir?: boolean;
     outputBaseDir?: string;
+    /** Treat React parity warnings as packaging errors. */
+    strictParity?: boolean;
+    /** Treat LXPack build warnings as packaging errors. */
+    strictBuild?: boolean;
 };
 type PackageLessonkitCourseResult = {
     ok: true;
@@ -275,6 +309,25 @@ type PackageLessonkitCourseResult = {
 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);
+ * ```
+ */
 declare function packageLessonkitCourse(options: PackageLessonkitCourseOptions): Promise<PackageLessonkitCourseResult>;
 
 type PackageValidationIssue = {
@@ -297,6 +350,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;
@@ -319,7 +377,128 @@ type ParseManifestResult = {
     ok: false;
     issues: ManifestParseIssue[];
 };
+/**
+ * Parse and validate a project-root `lessonkit.json` manifest (`schemaVersion: 1`).
+ * Pass `projectRoot` for path containment checks equivalent to the CLI.
+ */
 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, 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, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };