@lessonkit/lxpack 0.9.2 → 1.0.0

package/README.md

@@ -1,14 +1,12 @@
 # @lessonkit/lxpack
 
-[![Documentation](https://readthedocs.org/projects/lessonkit/badge/?version=latest)](https://lessonkit.readthedocs.io/en/latest/)
 [![npm](https://img.shields.io/npm/v/@lessonkit/lxpack.svg)](https://www.npmjs.com/package/@lessonkit/lxpack)
+[![Documentation](https://readthedocs.org/projects/lessonkit/badge/?version=latest)](https://lessonkit.readthedocs.io/en/latest/reference/packaging.html)
 [![License](https://img.shields.io/github/license/eddiethedean/lessonkit)](https://github.com/eddiethedean/lessonkit/blob/main/LICENSE)
 
-LXPack export adapter for LessonKit — write `lessonkit.json` + `course.yaml`, copy SPA builds, and package to SCORM / standalone / xAPI / cmi5 via [`@lxpack/api`](https://www.npmjs.com/package/@lxpack/api).
+Package Vite SPAs for LMS delivery — SCORM 1.2/2004, standalone, xAPI, and cmi5 via [`@lxpack/api`](https://www.npmjs.com/package/@lxpack/api).
 
-Requires **Node.js 20+**.
-
-**Docs:** [Packaging reference](https://lessonkit.readthedocs.io/en/latest/reference/packaging.html) · [Packaging & CLI guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/packaging-and-cli.html) · [Live examples](https://lessonkit.readthedocs.io/en/latest/examples/index.html)
+Requires Node.js **18+**.
 
 ## Install
 
@@ -16,14 +14,13 @@ Requires **Node.js 20+**.
 npm install @lessonkit/lxpack @lxpack/api
 ```
 
-## Quick start
+## Usage
 
-```ts
+```typescript
 import { packageLessonkitCourse } from "@lessonkit/lxpack";
-import { goldenCourseDescriptor } from "./course.descriptor";
 
 const result = await packageLessonkitCourse({
-  descriptor: goldenCourseDescriptor,
+  descriptor: courseDescriptor,
   outDir: ".lxpack/course",
   spaDistDir: "dist",
   target: "scorm12",
@@ -33,16 +30,20 @@ const result = await packageLessonkitCourse({
 if (!result.ok) throw new Error("packaging failed");
 ```
 
-See the [packaging reference](https://lessonkit.readthedocs.io/en/latest/reference/packaging.html) and the [`examples/lxpack-golden`](https://github.com/eddiethedean/lessonkit/tree/main/examples/lxpack-golden) course.
+Prefer the CLI: `lessonkit package --target scorm12` reads `lessonkit.json` and runs the same pipeline.
 
 ## Browser bridge
 
-When your React app runs inside an LXPack iframe:
+When embedded in an LXPack iframe, `@lessonkit/react` forwards completion events to `window.parent.lxpackBridge.v1`. Direct API:
 
-```ts
-import { notifyLxpackLessonComplete } from "@lessonkit/lxpack/bridge";
+```typescript
+import { forwardTelemetryToBridge } from "@lessonkit/lxpack/bridge";
 ```
 
-`@lessonkit/react` forwards `lesson_completed`, `course_completed`, and `quiz_completed` automatically when `window.parent.lxpackBridge.v1` is present (`config.lxpack.bridge: "off"` to disable).
+## Docs
+
+[Packaging reference](https://lessonkit.readthedocs.io/en/latest/reference/packaging.html) · [LXPack bridge](https://lessonkit.readthedocs.io/en/latest/reference/lxpack-bridge.html) · [Golden example](https://github.com/eddiethedean/lessonkit/tree/main/examples/lxpack-golden)
+
+## License
 
-For interoperability notes, see [LXPack upgrades](https://lessonkit.readthedocs.io/en/latest/reference/lxpack-upgrades.html). LXPack maintainers: [upgrade plan for maintainers](https://github.com/eddiethedean/lessonkit/blob/main/docs/LXPACK_UPGRADE_PLAN_FOR_MAINTAINERS.md).
+Apache-2.0

package/dist/bridge.cjs

@@ -25,6 +25,8 @@ __export(bridge_exports, {
   LXPACK_BRIDGE_VERSIONS: () => import_spa_bridge2.LXPACK_BRIDGE_VERSIONS,
   createLxpackBridge: () => createLxpackBridge,
   createLxpackBridgeHost: () => import_spa_bridge2.createLxpackBridgeHost,
+  dispatchBridgeAction: () => dispatchBridgeAction,
+  forwardTelemetryToBridge: () => forwardTelemetryToBridge,
   getLxpackBridge: () => import_spa_bridge2.getLxpackBridge,
   mapLessonkitTelemetryToBridgeAction: () => import_tracking_schema2.mapLessonkitTelemetryToBridgeAction,
   mapLessonkitTelemetryToLxpack: () => import_tracking_schema2.mapLessonkitTelemetryToLxpack,
@@ -42,6 +44,7 @@ module.exports = __toCommonJS(bridge_exports);
 var import_spa_bridge = require("@lxpack/spa-bridge");
 var import_spa_bridge2 = require("@lxpack/spa-bridge");
 var import_tracking_schema2 = require("@lxpack/tracking-schema");
+var import_tracking_schema3 = require("@lxpack/tracking-schema");
 
 // src/telemetry.ts
 var import_tracking_schema = require("@lxpack/tracking-schema");
@@ -93,6 +96,65 @@ function getBridge(parentWindow) {
   if (!parent || parent === window) return null;
   return parent.lxpack ?? null;
 }
+function isDevEnvironment() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function dispatchBridgeAction(bridge, action) {
+  if (!action) return;
+  try {
+    dispatchBridgeActionInner(bridge, action);
+  } catch (err) {
+    if (isDevEnvironment()) {
+      console.warn(
+        "[lessonkit/lxpack] lxpack bridge action failed:",
+        err instanceof Error ? err.message : err
+      );
+    }
+  }
+}
+function dispatchBridgeActionInner(bridge, action) {
+  if (!action) return;
+  switch (action.kind) {
+    case "completeLesson":
+      bridge.completeLesson?.(action.lessonId);
+      return;
+    case "completeCourse":
+      bridge.completeCourse?.();
+      return;
+    case "submitAssessment": {
+      const scaled = (0, import_spa_bridge.normalizeScore)({
+        score: action.score,
+        maxScore: action.maxScore
+      });
+      if (scaled === null) return;
+      bridge.submitAssessment?.({
+        id: action.id,
+        score: scaled,
+        passingScore: (0, import_spa_bridge.normalizePassingThreshold)({
+          passingScore: action.passingScore,
+          maxScore: action.maxScore
+        }),
+        maxScore: action.maxScore
+      });
+      return;
+    }
+    case "track":
+      bridge.track?.(action.event);
+      return;
+    default:
+      return;
+  }
+}
+function forwardTelemetryToBridge(event, mode = "auto", parentWindow) {
+  if (mode === "off") return;
+  const bridge = getBridge(parentWindow);
+  if (!bridge) return;
+  const lessonkitEvent = telemetryEventToLessonkit(event);
+  if (!lessonkitEvent) return;
+  const action = (0, import_tracking_schema3.mapLessonkitTelemetryToBridgeAction)(lessonkitEvent);
+  dispatchBridgeAction(bridge, action);
+}
 function createLxpackBridge() {
   return getBridge();
 }
@@ -121,6 +183,8 @@ function notifyLxpackAssessment(payload) {
   LXPACK_BRIDGE_VERSIONS,
   createLxpackBridge,
   createLxpackBridgeHost,
+  dispatchBridgeAction,
+  forwardTelemetryToBridge,
   getLxpackBridge,
   mapLessonkitTelemetryToBridgeAction,
   mapLessonkitTelemetryToLxpack,

package/dist/bridge.d.cts

@@ -1,6 +1,7 @@
-import { CheckId, LessonId } from '@lessonkit/core';
+import { TelemetryEvent, CheckId, LessonId } from '@lessonkit/core';
 import { LxpackBridgeV1, LxpackBridgeSubmitAssessmentPayload } from '@lxpack/spa-bridge';
 export { DEFAULT_BRIDGE_PASSING_SCORE, LXPACK_BRIDGE_VERSIONS, LxpackBridgeSubmitAssessmentPayload, LxpackBridgeV1, createLxpackBridgeHost, getLxpackBridge, normalizePassingThreshold, normalizeScore, supportedBridgeVersions } from '@lxpack/spa-bridge';
+import { mapLessonkitTelemetryToBridgeAction } from '@lxpack/tracking-schema';
 export { LESSONKIT_TELEMETRY_EVENTS, LessonkitBridgeAction, LessonkitTelemetryEvent, LessonkitTelemetryEventName, TrackingSchemaEvent, mapLessonkitTelemetryToBridgeAction, mapLessonkitTelemetryToLxpack } from '@lxpack/tracking-schema';
 export { t as telemetryEventToLessonkit } from './telemetry-gCxlwc7I.cjs';
 
@@ -20,6 +21,11 @@ declare function normalizeAssessmentPassingScore(opts?: {
     passingScore?: number;
     maxScore?: number;
 }): number;
+type LxpackBridgeMode = "auto" | "off";
+/** Apply a mapped bridge action to an LXPack bridge instance. */
+declare function dispatchBridgeAction(bridge: LxpackBridgeV1, action: ReturnType<typeof mapLessonkitTelemetryToBridgeAction>): void;
+/** Resolve bridge and dispatch a telemetry-derived action. */
+declare function forwardTelemetryToBridge(event: TelemetryEvent, mode?: LxpackBridgeMode, parentWindow?: Window): void;
 declare function createLxpackBridge(): LxpackBridgeV1 | null;
 declare function notifyLxpackLessonComplete(lessonId: LessonId): boolean;
 declare function notifyLxpackCourseComplete(): boolean;
@@ -31,4 +37,4 @@ declare function notifyLxpackAssessment(payload: LxpackBridgeSubmitAssessmentPay
     id: CheckId;
 }): boolean;
 
-export { createLxpackBridge, normalizeAssessmentPassingScore, normalizeAssessmentScore, notifyLxpackAssessment, notifyLxpackCourseComplete, notifyLxpackLessonComplete };
+export { type LxpackBridgeMode, createLxpackBridge, dispatchBridgeAction, forwardTelemetryToBridge, normalizeAssessmentPassingScore, normalizeAssessmentScore, notifyLxpackAssessment, notifyLxpackCourseComplete, notifyLxpackLessonComplete };

package/dist/bridge.d.ts

@@ -1,6 +1,7 @@
-import { CheckId, LessonId } from '@lessonkit/core';
+import { TelemetryEvent, CheckId, LessonId } from '@lessonkit/core';
 import { LxpackBridgeV1, LxpackBridgeSubmitAssessmentPayload } from '@lxpack/spa-bridge';
 export { DEFAULT_BRIDGE_PASSING_SCORE, LXPACK_BRIDGE_VERSIONS, LxpackBridgeSubmitAssessmentPayload, LxpackBridgeV1, createLxpackBridgeHost, getLxpackBridge, normalizePassingThreshold, normalizeScore, supportedBridgeVersions } from '@lxpack/spa-bridge';
+import { mapLessonkitTelemetryToBridgeAction } from '@lxpack/tracking-schema';
 export { LESSONKIT_TELEMETRY_EVENTS, LessonkitBridgeAction, LessonkitTelemetryEvent, LessonkitTelemetryEventName, TrackingSchemaEvent, mapLessonkitTelemetryToBridgeAction, mapLessonkitTelemetryToLxpack } from '@lxpack/tracking-schema';
 export { t as telemetryEventToLessonkit } from './telemetry-gCxlwc7I.js';
 
@@ -20,6 +21,11 @@ declare function normalizeAssessmentPassingScore(opts?: {
     passingScore?: number;
     maxScore?: number;
 }): number;
+type LxpackBridgeMode = "auto" | "off";
+/** Apply a mapped bridge action to an LXPack bridge instance. */
+declare function dispatchBridgeAction(bridge: LxpackBridgeV1, action: ReturnType<typeof mapLessonkitTelemetryToBridgeAction>): void;
+/** Resolve bridge and dispatch a telemetry-derived action. */
+declare function forwardTelemetryToBridge(event: TelemetryEvent, mode?: LxpackBridgeMode, parentWindow?: Window): void;
 declare function createLxpackBridge(): LxpackBridgeV1 | null;
 declare function notifyLxpackLessonComplete(lessonId: LessonId): boolean;
 declare function notifyLxpackCourseComplete(): boolean;
@@ -31,4 +37,4 @@ declare function notifyLxpackAssessment(payload: LxpackBridgeSubmitAssessmentPay
     id: CheckId;
 }): boolean;
 
-export { createLxpackBridge, normalizeAssessmentPassingScore, normalizeAssessmentScore, notifyLxpackAssessment, notifyLxpackCourseComplete, notifyLxpackLessonComplete };
+export { type LxpackBridgeMode, createLxpackBridge, dispatchBridgeAction, forwardTelemetryToBridge, normalizeAssessmentPassingScore, normalizeAssessmentScore, notifyLxpackAssessment, notifyLxpackCourseComplete, notifyLxpackLessonComplete };

package/dist/bridge.js

@@ -9,7 +9,7 @@ import {
   normalizeScore
 } from "@lxpack/spa-bridge";
 import {
-  createLxpackBridgeHost as createLxpackBridgeHost2,
+  createLxpackBridgeHost,
   DEFAULT_BRIDGE_PASSING_SCORE,
   getLxpackBridge,
   LXPACK_BRIDGE_VERSIONS,
@@ -22,6 +22,7 @@ import {
   mapLessonkitTelemetryToBridgeAction,
   mapLessonkitTelemetryToLxpack
 } from "@lxpack/tracking-schema";
+import { mapLessonkitTelemetryToBridgeAction as mapLessonkitTelemetryToBridgeAction2 } from "@lxpack/tracking-schema";
 function normalizeAssessmentScore(opts) {
   if (typeof opts.score !== "number" || !Number.isFinite(opts.score)) {
     return null;
@@ -42,6 +43,65 @@ function getBridge(parentWindow) {
   if (!parent || parent === window) return null;
   return parent.lxpack ?? null;
 }
+function isDevEnvironment() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function dispatchBridgeAction(bridge, action) {
+  if (!action) return;
+  try {
+    dispatchBridgeActionInner(bridge, action);
+  } catch (err) {
+    if (isDevEnvironment()) {
+      console.warn(
+        "[lessonkit/lxpack] lxpack bridge action failed:",
+        err instanceof Error ? err.message : err
+      );
+    }
+  }
+}
+function dispatchBridgeActionInner(bridge, action) {
+  if (!action) return;
+  switch (action.kind) {
+    case "completeLesson":
+      bridge.completeLesson?.(action.lessonId);
+      return;
+    case "completeCourse":
+      bridge.completeCourse?.();
+      return;
+    case "submitAssessment": {
+      const scaled = normalizeScore({
+        score: action.score,
+        maxScore: action.maxScore
+      });
+      if (scaled === null) return;
+      bridge.submitAssessment?.({
+        id: action.id,
+        score: scaled,
+        passingScore: normalizePassingThreshold({
+          passingScore: action.passingScore,
+          maxScore: action.maxScore
+        }),
+        maxScore: action.maxScore
+      });
+      return;
+    }
+    case "track":
+      bridge.track?.(action.event);
+      return;
+    default:
+      return;
+  }
+}
+function forwardTelemetryToBridge(event, mode = "auto", parentWindow) {
+  if (mode === "off") return;
+  const bridge = getBridge(parentWindow);
+  if (!bridge) return;
+  const lessonkitEvent = telemetryEventToLessonkit(event);
+  if (!lessonkitEvent) return;
+  const action = mapLessonkitTelemetryToBridgeAction2(lessonkitEvent);
+  dispatchBridgeAction(bridge, action);
+}
 function createLxpackBridge() {
   return getBridge();
 }
@@ -68,7 +128,9 @@ export {
   LESSONKIT_TELEMETRY_EVENTS,
   LXPACK_BRIDGE_VERSIONS,
   createLxpackBridge,
-  createLxpackBridgeHost2 as createLxpackBridgeHost,
+  createLxpackBridgeHost,
+  dispatchBridgeAction,
+  forwardTelemetryToBridge,
   getLxpackBridge,
   mapLessonkitTelemetryToBridgeAction,
   mapLessonkitTelemetryToLxpack,