@lxpack/scorm 0.1.1 → 0.2.0

package/README.md

@@ -5,15 +5,16 @@
 [![License](https://img.shields.io/github/license/eddiethedean/lxpack)](https://github.com/eddiethedean/lxpack/blob/main/LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)
 
-SCORM 1.2 and standalone HTML export for LXPack courses.
+SCORM 1.2, SCORM 2004 (multi-SCO), and standalone HTML export for LXPack courses.
 
-Part of [LXPack](https://github.com/eddiethedean/lxpack) — an AI-native learning experience compiler and runtime.
+Part of [LXPack](https://github.com/eddiethedean/lxpack) — an AI-native learning experience compiler and runtime (**v0.2.0**).
 
 | Related | Package |
 |---------|---------|
 | CLI | [`@lxpack/cli`](../cli/README.md) |
 | Manifest validation | [`@lxpack/validators`](../validators/README.md) |
 | Embedded client | [`@lxpack/runtime`](../runtime/README.md) |
+| Components bundle | [`@lxpack/components`](../components/README.md) |
 
 ## Install
 
@@ -25,6 +26,8 @@ Requires Node.js 20+.
 
 ## Usage
 
+### SCORM 1.2 or standalone ZIP
+
 ```ts
 import { readFile } from "node:fs/promises";
 import type { CourseManifest } from "@lxpack/validators";
@@ -44,6 +47,7 @@ const assessmentBundle = await buildRuntimeAssessmentBundle(courseDir, manifest)
 
 const runtimeClientJs = await readFile("path/to/client.js", "utf8");
 const runtimeCss = await readFile("path/to/styles.css", "utf8");
+const componentsJs = await readFile("path/to/bundle.js", "utf8"); // optional
 
 await packageCourse({
   courseDir,
@@ -52,10 +56,31 @@ await packageCourse({
   outputPath: "/path/to/output/course-scorm12.zip",
   runtimeClientJs,
   runtimeCss,
+  componentsJs,
+  assessmentBundle,
+});
+```
+
+### SCORM 2004 multi-SCO
+
+```ts
+import { packageScorm2004, buildScoIndexHtml, listCourseActivities } from "@lxpack/scorm";
+
+const activities = listCourseActivities(manifest);
+
+await packageScorm2004({
+  courseDir,
+  manifest,
+  outputPath: "/path/to/output/course-scorm2004.zip",
+  runtimeClientJs,
+  runtimeCss,
+  componentsJs,
   assessmentBundle,
 });
 ```
 
+Each activity gets `sco/<activityId>/index.html` (via `buildScoIndexHtml`). Shared assets include `lxpack-runtime.js` and `lxpack-components.js`. `generateScorm2004Manifest` emits `imsmanifest.xml` with IMS Simple Sequencing metadata.
+
 ### Standalone directory
 
 ```ts
@@ -66,6 +91,7 @@ await packageStandaloneDir({
   outputDir: "/path/to/output/standalone",
   runtimeClientJs,
   runtimeCss,
+  componentsJs,
   assessmentBundle,
 });
 ```
@@ -77,16 +103,21 @@ Most users should use `lxpack build` from [`@lxpack/cli`](../cli/README.md) inst
 | Export | Description |
 |--------|-------------|
 | `packageCourse(options)` | Build a SCORM 1.2 or standalone ZIP |
-| `packageStandaloneDir(options)` | Write an unpacked directory (ZIP or SCORM layout) |
+| `packageScorm2004(options)` | Build a SCORM 2004 multi-SCO ZIP |
+| `packageStandaloneDir(options)` | Write an unpacked directory |
+| `listCourseActivities(manifest)` | Ordered activities for multi-SCO layout |
 | `generateImsManifest(manifest, files)` | SCORM 1.2 `imsmanifest.xml` |
-| `buildIndexHtml(options)` | Course shell HTML with embedded config |
+| `generateScorm2004Manifest(...)` | SCORM 2004 manifest with sequencing |
+| `buildIndexHtml(options)` | Single-SCO course shell HTML |
+| `buildScoIndexHtml(options)` | Per-activity launch HTML for SCORM 2004 |
+| `scoLaunchPath(activityId)` | Relative launch path (`sco/<id>/index.html`) |
 | `buildRuntimeConfig(options)` | Config object passed to `safeJsonForHtml` |
 | `collectFiles(courseDir, baseDir)` | Course assets for packaging (respects skip rules) |
 | `shouldSkipCourseFile(rel)` | Whether a relative path is omitted from exports |
 | `buildManifestFileList(courseFiles)` | File list for `imsmanifest.xml` |
 | `safeJsonForHtml(value)` | JSON safe for `<script type="application/json">` blocks |
 | `courseSlug(manifest)` | Stable slug for ZIP names and manifest identifiers |
-| `ExportTarget` | `"scorm12"` \| `"standalone"` |
+| `ExportTarget` | `"scorm12"` \| `"scorm2004"` \| `"standalone"` |
 
 ### `PackageOptions`
 
@@ -94,28 +125,30 @@ Most users should use `lxpack build` from [`@lxpack/cli`](../cli/README.md) inst
 |-------|-------------|
 | `courseDir` | Course root directory |
 | `manifest` | Parsed `course.yaml` |
-| `outputPath` | Destination ZIP path (`packageCourse`) |
-| `target` | `scorm12` or `standalone` |
+| `outputPath` | Destination ZIP path |
+| `target` | `scorm12`, `scorm2004`, or `standalone` |
 | `runtimeClientJs` | Contents of `@lxpack/runtime/client` bundle |
 | `runtimeCss` | Runtime stylesheet |
-| `assessmentBundle` | Optional; from `buildRuntimeAssessmentBundle()` |
+| `componentsJs` | Optional `@lxpack/components/bundle` for component lessons |
+| `assessmentBundle` | From `buildRuntimeAssessmentBundle()` (assessments, keys, configs, feedback) |
 
 ## What gets packaged
 
 **Included**
 
-- Lessons, interactions, and assets referenced by the manifest
-- `index.html` — shell with embedded manifest + assessment config
+- Lessons, interactions, assets, and component overrides referenced by the manifest
 - `lxpack-runtime.js` — browser client bundle
-- `imsmanifest.xml` — SCORM 1.2 target only
+- `lxpack-components.js` — when component lessons are used
+- **SCORM 1.2 / standalone:** root `index.html` with embedded config
+- **SCORM 2004:** `sco/<activityId>/index.html` per activity + `imsmanifest.xml`
 
 **Excluded** (`shouldSkipCourseFile`)
 
 - `course.yaml`, `lxpack.config.json`, `.lxpack/`
 - `assessments/**` — author YAML; assessments are embedded in config instead
-- Root `index.html` if present (packager generates the entry page)
+- Root `index.html` if present (packager generates entry pages)
 
-Answer keys are only present inside the JSON config block (with `<` escaped via `safeJsonForHtml`), not as downloadable files.
+Answer keys and feedback text are only present inside the JSON config block (with `<` escaped via `safeJsonForHtml`), not as downloadable files.
 
 ## Development
 
@@ -130,6 +163,8 @@ pnpm --filter @lxpack/scorm typecheck
 ## Links
 
 - [LXPack repository](https://github.com/eddiethedean/lxpack)
+- [Documentation index](https://github.com/eddiethedean/lxpack/blob/main/docs/README.md)
+- [Roadmap & phases](https://github.com/eddiethedean/lxpack/blob/main/docs/ROADMAP.md)
 - [Changelog](https://github.com/eddiethedean/lxpack/blob/main/CHANGELOG.md)
 
 ## License

package/dist/index.d.ts

@@ -6,19 +6,18 @@ declare function generateImsManifest(manifest: CourseManifest, files: string[],
 interface BuildHtmlOptions {
     manifest: CourseManifest;
     runtimeCss: string;
-    mode: "standalone" | "scorm12";
+    mode: "standalone" | "scorm12" | "scorm2004";
+    activityId?: string;
     assessmentBundle?: RuntimeAssessmentBundle;
+    componentsScript?: string;
 }
-declare function buildRuntimeConfig(options: BuildHtmlOptions): {
-    manifest: CourseManifest;
-    baseUrl: string;
-    mode: BuildHtmlOptions["mode"];
-    assessments?: RuntimeAssessmentBundle["assessments"];
-    answerKeys?: RuntimeAssessmentBundle["answerKeys"];
-};
+declare function buildRuntimeConfig(options: BuildHtmlOptions): Record<string, unknown>;
+declare function buildScoIndexHtml(options: BuildHtmlOptions & {
+    activityId: string;
+}): string;
 declare function buildIndexHtml(options: BuildHtmlOptions): string;
 
-type ExportTarget = "scorm12" | "standalone";
+type ExportTarget = "scorm12" | "scorm2004" | "standalone";
 interface PackageOptions {
     courseDir: string;
     manifest: CourseManifest;
@@ -26,6 +25,7 @@ interface PackageOptions {
     target: ExportTarget;
     runtimeClientJs: string;
     runtimeCss: string;
+    componentsBundleJs?: string;
     assessmentBundle?: RuntimeAssessmentBundle;
 }
 declare function shouldSkipCourseFile(rel: string): boolean;
@@ -36,6 +36,10 @@ declare function collectFiles(dir: string, baseDir: string): Promise<Array<{
 declare function buildManifestFileList(courseFiles: Array<{
     path: string;
 }>): string[];
+declare function packageScorm2004(options: PackageOptions): Promise<{
+    outputPath: string;
+    fileCount: number;
+}>;
 declare function packageCourse(options: PackageOptions): Promise<{
     outputPath: string;
     fileCount: number;
@@ -53,4 +57,15 @@ declare function safeJsonForHtml(value: unknown): string;
 /** Stable slug for ZIP filenames and SCORM identifiers. */
 declare function courseSlug(manifest: CourseManifest): string;
 
-export { type BuildHtmlOptions, type ExportTarget, type PackageOptions, buildIndexHtml, buildManifestFileList, buildRuntimeConfig, collectFiles, courseSlug, generateImsManifest, manifestIdentifier, packageCourse, packageStandaloneDir, safeJsonForHtml, shouldSkipCourseFile };
+interface CourseActivity {
+    id: string;
+    title: string;
+    kind: "lesson" | "assessment";
+}
+declare function listCourseActivities(manifest: CourseManifest): CourseActivity[];
+
+declare function scoLaunchPath(activityId: string): string;
+declare function buildScorm2004ManifestFiles(manifest: CourseManifest, courseFiles: string[]): string[];
+declare function generateScorm2004Manifest(manifest: CourseManifest, courseFiles: string[]): string;
+
+export { type BuildHtmlOptions, type CourseActivity, type ExportTarget, type PackageOptions, buildIndexHtml, buildManifestFileList, buildRuntimeConfig, buildScoIndexHtml, buildScorm2004ManifestFiles, collectFiles, courseSlug, generateImsManifest, generateScorm2004Manifest, listCourseActivities, manifestIdentifier, packageCourse, packageScorm2004, packageStandaloneDir, safeJsonForHtml, scoLaunchPath, shouldSkipCourseFile };

package/dist/index.js

@@ -59,20 +59,47 @@ function safeJsonForHtml(value) {
 
 // src/build-html.ts
 function buildRuntimeConfig(options) {
-  const { manifest, mode, assessmentBundle } = options;
+  const { manifest, mode, assessmentBundle, activityId } = options;
   return {
     manifest,
     baseUrl: ".",
     mode,
+    ...activityId ? { activityId } : {},
     ...assessmentBundle ? {
       assessments: assessmentBundle.assessments,
-      answerKeys: assessmentBundle.answerKeys
+      answerKeys: assessmentBundle.answerKeys,
+      assessmentConfigs: assessmentBundle.configs,
+      assessmentFeedback: assessmentBundle.feedback
     } : {}
   };
 }
+function buildScoIndexHtml(options) {
+  const { manifest, runtimeCss, activityId, componentsScript } = options;
+  const config = safeJsonForHtml(buildRuntimeConfig({ ...options, activityId }));
+  const componentsTag = componentsScript ? `<script type="module" src="${escapeHtml(componentsScript)}"></script>` : "";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(manifest.title)} \u2014 ${escapeHtml(activityId)}</title>
+  <style>${runtimeCss}</style>
+</head>
+<body>
+  <div id="lxpack-app"></div>
+  <script type="application/json" id="lxpack-config">${config}</script>
+  <script>
+    window.__LXPACK_CONFIG__ = JSON.parse(document.getElementById('lxpack-config').textContent);
+  </script>
+  ${componentsTag}
+  <script type="module" src="../../lxpack-runtime.js"></script>
+</body>
+</html>`;
+}
 function buildIndexHtml(options) {
-  const { manifest, runtimeCss } = options;
+  const { manifest, runtimeCss, componentsScript } = options;
   const config = safeJsonForHtml(buildRuntimeConfig(options));
+  const componentsTag = componentsScript ? `<script type="module" src="${escapeHtml(componentsScript)}"></script>` : "";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -87,6 +114,7 @@ function buildIndexHtml(options) {
   <script>
     window.__LXPACK_CONFIG__ = JSON.parse(document.getElementById('lxpack-config').textContent);
   </script>
+  ${componentsTag}
   <script type="module" src="./lxpack-runtime.js"></script>
 </body>
 </html>`;
@@ -100,6 +128,103 @@ import { readFile, readdir, writeFile, mkdir, cp } from "fs/promises";
 import { existsSync } from "fs";
 import { dirname, join, relative } from "path";
 import JSZip from "jszip";
+
+// src/activities.ts
+function listCourseActivities(manifest) {
+  const activities = manifest.lessons.map((lesson) => ({
+    id: lesson.id,
+    title: lesson.title ?? lesson.id,
+    kind: "lesson"
+  }));
+  for (const ref of manifest.assessments ?? []) {
+    activities.push({
+      id: ref.id,
+      title: ref.id.replace(/_/g, " "),
+      kind: "assessment"
+    });
+  }
+  return activities;
+}
+
+// src/scorm2004-manifest.ts
+function escapeXml2(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function scoLaunchPath(activityId) {
+  return `sco/${activityId}/index.html`;
+}
+function buildScorm2004ManifestFiles(manifest, courseFiles) {
+  const activities = listCourseActivities(manifest);
+  const scoFiles = activities.map((a) => scoLaunchPath(a.id));
+  return [
+    "lxpack-runtime.js",
+    "lxpack-components.js",
+    ...scoFiles,
+    ...courseFiles
+  ];
+}
+function generateScorm2004Manifest(manifest, courseFiles) {
+  const identifier = manifestIdentifier(manifest);
+  const orgId = `${identifier}-org`;
+  const activities = listCourseActivities(manifest);
+  const itemEntries = activities.map((activity) => {
+    const itemId = `item_${activity.id}`;
+    const resourceId = `res_${activity.id}`;
+    const sequencing = activity.kind === "assessment" ? `
+        <imsss:sequencing>
+          <imsss:deliveryControls tracked="true" completionSetByContent="true" objectiveSetByContent="true"/>
+        </imsss:sequencing>` : `
+        <imsss:sequencing>
+          <imsss:deliveryControls tracked="true" completionSetByContent="true"/>
+        </imsss:sequencing>`;
+    return `      <item identifier="${escapeXml2(itemId)}" identifierref="${escapeXml2(resourceId)}">
+        <title>${escapeXml2(activity.title)}</title>${sequencing}
+      </item>`;
+  }).join("\n");
+  const resources = activities.map((activity) => {
+    const resourceId = `res_${activity.id}`;
+    const href = scoLaunchPath(activity.id);
+    return `    <resource identifier="${escapeXml2(resourceId)}" type="webcontent" adlcp:scormType="sco" href="${escapeXml2(href)}">
+      <file href="${escapeXml2(href)}"/>
+      <file href="lxpack-runtime.js"/>
+      <file href="lxpack-components.js"/>
+    </resource>`;
+  }).join("\n");
+  const orgSequencing = `
+    <imsss:sequencing>
+      <imsss:controlMode choice="true" flow="true"/>
+    </imsss:sequencing>`;
+  const uniqueCourseFiles = [...new Set(courseFiles)].filter((f) => !f.startsWith("sco/")).map(
+    (href) => `      <file href="${escapeXml2(href)}"/>`
+  ).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<manifest identifier="${escapeXml2(identifier)}" version="${escapeXml2(manifest.version)}"
+  xmlns="http://www.imsglobal.org/xsd/imscp_v1p1"
+  xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_v1p3"
+  xmlns:adlseq="http://www.adlnet.org/xsd/adlseq_v1p3"
+  xmlns:imsss="http://www.imsglobal.org/xsd/imsss"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <metadata>
+    <schema>ADL SCORM</schema>
+    <schemaversion>2004 4th Edition</schemaversion>
+  </metadata>
+  <organizations default="${escapeXml2(orgId)}">
+    <organization identifier="${escapeXml2(orgId)}">${orgSequencing}
+${itemEntries}
+    </organization>
+  </organizations>
+  <resources>
+${resources}
+    <resource identifier="shared_assets" type="webcontent" adlcp:scormType="asset">
+${uniqueCourseFiles}
+      <file href="lxpack-runtime.js"/>
+      <file href="lxpack-components.js"/>
+    </resource>
+  </resources>
+</manifest>`;
+}
+
+// src/package.ts
 var SKIP_FILES = /* @__PURE__ */ new Set([
   "course.yaml",
   "lxpack.config.ts",
@@ -140,7 +265,57 @@ async function collectFiles(dir, baseDir) {
 function buildManifestFileList(courseFiles) {
   return ["index.html", "lxpack-runtime.js", ...courseFiles.map((f) => f.path)];
 }
+async function packageScorm2004(options) {
+  const {
+    courseDir,
+    manifest,
+    outputPath,
+    runtimeClientJs,
+    runtimeCss,
+    componentsBundleJs,
+    assessmentBundle
+  } = options;
+  const zip = new JSZip();
+  const courseFiles = await collectFiles(courseDir, courseDir);
+  for (const file of courseFiles) {
+    const content = await readFile(file.fullPath);
+    zip.file(file.path, content);
+  }
+  zip.file("lxpack-runtime.js", runtimeClientJs);
+  if (componentsBundleJs) {
+    zip.file("lxpack-components.js", componentsBundleJs);
+  }
+  const activities = listCourseActivities(manifest);
+  for (const activity of activities) {
+    const html = buildScoIndexHtml({
+      manifest,
+      runtimeCss,
+      mode: "scorm2004",
+      activityId: activity.id,
+      assessmentBundle,
+      componentsScript: componentsBundleJs ? "../../lxpack-components.js" : void 0
+    });
+    zip.file(`sco/${activity.id}/index.html`, html);
+  }
+  const manifestFiles = buildScorm2004ManifestFiles(
+    manifest,
+    courseFiles.map((f) => f.path)
+  );
+  zip.file("imsmanifest.xml", generateScorm2004Manifest(manifest, manifestFiles));
+  const buffer = await zip.generateAsync({
+    type: "nodebuffer",
+    compression: "DEFLATE"
+  });
+  await writeFile(outputPath, buffer);
+  return {
+    outputPath,
+    fileCount: Object.keys(zip.files).length
+  };
+}
 async function packageCourse(options) {
+  if (options.target === "scorm2004") {
+    return packageScorm2004(options);
+  }
   const {
     courseDir,
     manifest,
@@ -148,7 +323,8 @@ async function packageCourse(options) {
     target,
     runtimeClientJs,
     runtimeCss,
-    assessmentBundle
+    assessmentBundle,
+    componentsBundleJs
   } = options;
   const zip = new JSZip();
   const mode = target === "scorm12" ? "scorm12" : "standalone";
@@ -161,10 +337,14 @@ async function packageCourse(options) {
     manifest,
     runtimeCss,
     mode,
-    assessmentBundle
+    assessmentBundle,
+    componentsScript: componentsBundleJs ? "./lxpack-components.js" : void 0
   });
   zip.file("index.html", indexHtml);
   zip.file("lxpack-runtime.js", runtimeClientJs);
+  if (componentsBundleJs) {
+    zip.file("lxpack-components.js", componentsBundleJs);
+  }
   if (target === "scorm12") {
     const manifestFiles = buildManifestFileList(courseFiles);
     zip.file(
@@ -228,12 +408,18 @@ export {
   buildIndexHtml,
   buildManifestFileList,
   buildRuntimeConfig,
+  buildScoIndexHtml,
+  buildScorm2004ManifestFiles,
   collectFiles,
   courseSlug,
   generateImsManifest,
+  generateScorm2004Manifest,
+  listCourseActivities,
   manifestIdentifier,
   packageCourse,
+  packageScorm2004,
   packageStandaloneDir,
   safeJsonForHtml,
+  scoLaunchPath,
   shouldSkipCourseFile
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lxpack/scorm",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "SCORM and standalone HTML export for LXPack",
   "license": "Apache-2.0",
   "repository": {
@@ -39,7 +39,7 @@
   ],
   "dependencies": {
     "jszip": "^3.10.1",
-    "@lxpack/validators": "0.1.1"
+    "@lxpack/validators": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",