@lessonkit/lxpack 1.4.0 → 1.6.0

package/README.md

@@ -4,9 +4,15 @@
 [![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)
 
-Package Vite SPAs for LMS delivery — SCORM 1.2/2004, standalone, xAPI, and cmi5. `@lessonkit/lxpack` bundles [`@lxpack/*`](https://www.npmjs.com/org/lxpack) as direct dependencies (no separate `@lxpack/api` install).
+Package Vite SPAs for LMS delivery — SCORM 1.2/2004, standalone, xAPI, and cmi5. Bundles [`@lxpack/*`](https://www.npmjs.com/org/lxpack) as direct dependencies.
 
-Requires Node.js **18+**.
+## When to install
+
+- Custom packaging pipelines without the CLI
+- Validating `lessonkit.json` / course descriptors in CI
+- Programmatic LMS export from your own build tools
+
+Most authors use `lessonkit package` (CLI) which calls this package internally.
 
 ## Install
 
@@ -14,13 +20,18 @@ Requires Node.js **18+**.
 npm install @lessonkit/lxpack
 ```
 
+Requires Node.js **18+** minimum; **20.19+** recommended for CLI scaffold workflows.
+
 ## Usage
 
 ```typescript
-import { packageLessonkitCourse } from "@lessonkit/lxpack";
+import { packageLessonkitCourse, parseLessonkitManifest } from "@lessonkit/lxpack";
+
+const manifest = parseLessonkitManifest(await readFile("lessonkit.json", "utf8"));
+if (!manifest.ok) throw manifest.error;
 
 const result = await packageLessonkitCourse({
-  descriptor: courseDescriptor,
+  descriptor: manifest.value,
   outDir: ".lxpack/course",
   spaDistDir: "dist",
   target: "scorm12",
@@ -30,19 +41,50 @@ const result = await packageLessonkitCourse({
 if (!result.ok) throw new Error("packaging failed");
 ```
 
-Prefer the CLI: `lessonkit package --target scorm12` reads `lessonkit.json` and runs the same pipeline.
+Prefer the CLI: `lessonkit package --target scorm12` reads `lessonkit.json` and runs the same staged pipeline.
+
+## Layouts
+
+| Layout | Use case |
+| --- | --- |
+| `single-spa` | One Vite SPA for the whole course (CLI default) |
+| `per-lesson-spa` | One dist per lesson (advanced; see packaging reference) |
+
+## Portable interchange (1.6.0)
+
+Export a `.lkcourse` archive for team handoff (not LMS upload):
+
+```typescript
+import { exportLkcourse, validateLkcourse, importLkcourse } from "@lessonkit/lxpack";
+
+await exportLkcourse({ projectRoot, manifest, includeBlockTree: true });
+validateLkcourse("course.lkcourse");
+await importLkcourse({ archivePath: "course.lkcourse", targetDir: "./restored" });
+```
+
+Schemas: `@lessonkit/lxpack/lkcourse-format.v1.json`, `@lessonkit/lxpack/block-tree.v1.json`. See [Portable interchange](https://lessonkit.readthedocs.io/en/latest/reference/interchange.html).
 
 ## Browser bridge
 
-When embedded in an LXPack iframe, `@lessonkit/react` forwards completion events to `window.parent.lxpackBridge.v1`. Direct API:
+When embedded in an LXPack iframe, `@lessonkit/react` forwards completion events to `window.parent.lxpackBridge.v1`:
 
 ```typescript
 import { forwardTelemetryToBridge } from "@lessonkit/lxpack/bridge";
 ```
 
+Production builds require `allowedParentOrigins` when `bridge: "auto"`.
+
+## Common issues
+
+| Symptom | Fix |
+| --- | --- |
+| React/manifest ID mismatch | Run strict parity validation; align IDs in `App.tsx` and `lessonkit.json` |
+| xAPI/cmi5 validation failure | Set HTTPS `activityIri` in manifest |
+| Empty `dist/` | Run `lessonkit build` before `package` (or omit `--no-build`) |
+
 ## 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)
+[Packaging reference](https://lessonkit.readthedocs.io/en/latest/reference/packaging.html) · [LXPack bridge](https://lessonkit.readthedocs.io/en/latest/reference/lxpack-bridge.html) · [Manifest](https://lessonkit.readthedocs.io/en/latest/reference/manifest.html) · [Golden example](https://github.com/eddiethedean/lessonkit/tree/main/examples/lxpack-golden) · [TypeDoc API index](https://lessonkit.readthedocs.io/en/latest/reference/api.html)
 
 ## License
 

package/block-tree.v1.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lessonkit.dev/schemas/block-tree.v1.json",
+  "title": "BlockTreeV1",
+  "description": "Best-effort static JSX block inventory for a LessonKit course",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "blocks", "sources"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "sources": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "blocks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/BlockTreeNode" }
+    }
+  },
+  "$defs": {
+    "BlockTreeNode": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "rawTag": { "type": "string" },
+        "courseId": { "type": "string" },
+        "lessonId": { "type": "string" },
+        "checkId": { "type": "string" },
+        "blockId": { "type": "string" },
+        "nodeId": { "type": "string" },
+        "children": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/BlockTreeNode" }
+        }
+      }
+    }
+  }
+}

package/dist/bridge.cjs

@@ -20,23 +20,27 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/bridge.ts
 var bridge_exports = {};
 __export(bridge_exports, {
+  BRANCH_TELEMETRY_EVENTS: () => BRANCH_TELEMETRY_EVENTS,
   DEFAULT_BRIDGE_PASSING_SCORE: () => import_spa_bridge2.DEFAULT_BRIDGE_PASSING_SCORE,
   LESSONKIT_TELEMETRY_EVENTS: () => import_tracking_schema2.LESSONKIT_TELEMETRY_EVENTS,
   LXPACK_BRIDGE_VERSIONS: () => import_spa_bridge2.LXPACK_BRIDGE_VERSIONS,
+  branchTelemetryToBridgeTrackEvent: () => branchTelemetryToBridgeTrackEvent,
   createLxpackBridge: () => createLxpackBridge,
   createLxpackBridgeHost: () => import_spa_bridge2.createLxpackBridgeHost,
   dispatchBridgeAction: () => dispatchBridgeAction,
   forwardTelemetryToBridge: () => forwardTelemetryToBridge,
-  getLxpackBridge: () => import_spa_bridge2.getLxpackBridge,
+  getLxpackBridge: () => getLxpackBridge,
+  isParentOriginAllowed: () => isParentOriginAllowed,
   mapLessonkitTelemetryToBridgeAction: () => import_tracking_schema2.mapLessonkitTelemetryToBridgeAction,
   mapLessonkitTelemetryToLxpack: () => import_tracking_schema2.mapLessonkitTelemetryToLxpack,
   normalizeAssessmentPassingScore: () => normalizeAssessmentPassingScore,
   normalizeAssessmentScore: () => normalizeAssessmentScore,
-  normalizePassingThreshold: () => import_spa_bridge2.normalizePassingThreshold,
-  normalizeScore: () => import_spa_bridge2.normalizeScore,
+  normalizePassingThreshold: () => normalizePassingThreshold,
+  normalizeScore: () => normalizeScore,
   notifyLxpackAssessment: () => notifyLxpackAssessment,
   notifyLxpackCourseComplete: () => notifyLxpackCourseComplete,
   notifyLxpackLessonComplete: () => notifyLxpackLessonComplete,
+  resolveParentOrigin: () => resolveParentOrigin,
   supportedBridgeVersions: () => import_spa_bridge2.supportedBridgeVersions,
   telemetryEventToLessonkit: () => telemetryEventToLessonkit
 });
@@ -48,56 +52,163 @@ var import_tracking_schema3 = require("@lxpack/tracking-schema");
 
 // src/telemetry.ts
 var import_tracking_schema = require("@lxpack/tracking-schema");
-var SUPPORTED = new Set(import_tracking_schema.LESSONKIT_TELEMETRY_EVENTS);
+var BRANCH_TELEMETRY_EVENTS = ["branch_node_viewed", "branch_selected"];
+var ASSESSMENT_TELEMETRY_EVENTS = ["assessment_answered"];
+var SUPPORTED = /* @__PURE__ */ new Set([
+  ...import_tracking_schema.LESSONKIT_TELEMETRY_EVENTS,
+  ...BRANCH_TELEMETRY_EVENTS,
+  ...ASSESSMENT_TELEMETRY_EVENTS
+]);
 function isQuizAnsweredData(data) {
-  return typeof data === "object" && data !== null && typeof data.checkId === "string";
+  return typeof data === "object" && data !== null && typeof data.checkId === "string" && data.checkId.length > 0;
 }
 function isQuizCompletedData(data) {
-  return typeof data === "object" && data !== null && typeof data.checkId === "string";
+  return typeof data === "object" && data !== null && typeof data.checkId === "string" && data.checkId.length > 0;
+}
+function isAssessmentAnsweredData(data) {
+  return typeof data === "object" && data !== null && typeof data.checkId === "string" && data.checkId.length > 0;
 }
 function isInteractionData(data) {
   return typeof data === "object" && data !== null;
 }
+function isBranchNodeViewedData(data) {
+  return typeof data === "object" && data !== null && typeof data.blockId === "string" && typeof data.nodeId === "string";
+}
+function isBranchSelectedData(data) {
+  return typeof data === "object" && data !== null && typeof data.blockId === "string" && typeof data.fromNodeId === "string" && typeof data.toNodeId === "string";
+}
 function telemetryEventToLessonkit(event) {
   if (!SUPPORTED.has(event.name)) {
     return null;
   }
-  const name = event.name;
   const mapped = {
-    name,
+    name: event.name,
     lessonId: event.lessonId
   };
-  if (name === "quiz_completed" || name === "quiz_answered") {
+  if (event.name === "quiz_completed" || event.name === "quiz_answered" || event.name === "assessment_answered") {
     const data = event.data;
-    if (isQuizAnsweredData(data) || isQuizCompletedData(data)) {
-      mapped.assessmentId = data.checkId;
-      if ("score" in data) {
-        mapped.score = data.score;
-        mapped.maxScore = data.maxScore;
-        mapped.passingScore = data.passingScore;
-      }
-      mapped.data = data;
+    if (!isQuizAnsweredData(data) && !isQuizCompletedData(data) && !isAssessmentAnsweredData(data)) {
+      return null;
     }
-  } else if (name === "interaction" && event.data && isInteractionData(event.data)) {
+    mapped.assessmentId = data.checkId;
+    if ("score" in data) {
+      mapped.score = data.score;
+      mapped.maxScore = data.maxScore;
+      mapped.passingScore = data.passingScore;
+    }
+    mapped.data = data;
+  } else if (mapped.name === "interaction" && event.data && isInteractionData(event.data)) {
+    mapped.data = event.data;
+  } else if (event.name === "branch_node_viewed" && isBranchNodeViewedData(event.data)) {
+    mapped.data = event.data;
+  } else if (event.name === "branch_selected" && isBranchSelectedData(event.data)) {
     mapped.data = event.data;
   }
   return mapped;
 }
+function answeredTelemetryToBridgeTrackEvent(event) {
+  if (event.name !== "quiz_answered" && event.name !== "assessment_answered") {
+    return null;
+  }
+  const lessonkitEvent = telemetryEventToLessonkit(event);
+  if (!lessonkitEvent?.assessmentId) return null;
+  return (0, import_tracking_schema.mapLessonkitTelemetryToLxpack)({
+    ...lessonkitEvent,
+    name: "quiz_answered"
+  });
+}
+function branchTelemetryToBridgeTrackEvent(event) {
+  if (event.name === "branch_node_viewed" && isBranchNodeViewedData(event.data)) {
+    return {
+      type: "interaction",
+      id: "branch_node_viewed",
+      data: { ...event.data, lessonkitEvent: event.name }
+    };
+  }
+  if (event.name === "branch_selected" && isBranchSelectedData(event.data)) {
+    return {
+      type: "interaction",
+      id: "branch_selected",
+      data: { ...event.data, lessonkitEvent: event.name }
+    };
+  }
+  return null;
+}
 
 // src/bridge.ts
+var import_meta = {};
+var DEFAULT_BRIDGE_PASSING_SCORE2 = 1;
+function clamp01(value) {
+  return Math.min(1, Math.max(0, value));
+}
+function normalizeScore(raw) {
+  const { score, maxScore } = raw;
+  if (typeof score !== "number" || !Number.isFinite(score)) return null;
+  if (typeof maxScore === "number" && maxScore > 0) {
+    return clamp01(score / maxScore);
+  }
+  if (score > 1 && score <= 100) {
+    return clamp01(score / 100);
+  }
+  return clamp01(score);
+}
+function normalizePassingThreshold(raw) {
+  const { passingScore, maxScore } = raw ?? {};
+  if (typeof passingScore !== "number" || !Number.isFinite(passingScore)) {
+    return DEFAULT_BRIDGE_PASSING_SCORE2;
+  }
+  if (typeof maxScore === "number" && maxScore > 1) {
+    return clamp01(passingScore / maxScore);
+  }
+  if (typeof maxScore === "number" && maxScore <= 1) {
+    return clamp01(passingScore);
+  }
+  if (passingScore > 1 && passingScore <= 100) {
+    return clamp01(passingScore / 100);
+  }
+  return clamp01(passingScore);
+}
 function normalizeAssessmentScore(opts) {
   if (typeof opts.score !== "number" || !Number.isFinite(opts.score)) {
     return null;
   }
-  return (0, import_spa_bridge.normalizeScore)({ score: opts.score, maxScore: opts.maxScore });
+  return normalizeScore({ score: opts.score, maxScore: opts.maxScore });
 }
 function normalizeAssessmentPassingScore(opts) {
-  return (0, import_spa_bridge.normalizePassingThreshold)({
+  return normalizePassingThreshold({
     passingScore: opts?.passingScore,
     maxScore: opts?.maxScore
   });
 }
-function getBridge(parentWindow) {
+function resolveParentOrigin(parentWindow) {
+  if (typeof window === "undefined") return null;
+  const parent = parentWindow ?? window.parent;
+  if (!parent || parent === window) return null;
+  try {
+    return parent.location.origin;
+  } catch {
+    return null;
+  }
+}
+function isProductionRuntime() {
+  try {
+    if (import_meta.env?.PROD === true) return true;
+  } catch {
+  }
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production";
+}
+function isParentOriginAllowed(allowedParentOrigins, parentWindow, mode) {
+  if (mode === "off") return false;
+  if (isProductionRuntime() && !allowedParentOrigins?.length) return false;
+  if (!allowedParentOrigins?.length) return true;
+  const origin = resolveParentOrigin(parentWindow);
+  if (!origin) return false;
+  return allowedParentOrigins.includes(origin);
+}
+function getBridge(parentWindow, opts) {
+  const mode = opts?.mode ?? "auto";
+  if (!isParentOriginAllowed(opts?.allowedParentOrigins, parentWindow, mode)) return null;
   const fromSdk = (0, import_spa_bridge.getLxpackBridge)(parentWindow);
   if (fromSdk) return fromSdk;
   if (typeof window === "undefined") return null;
@@ -105,21 +216,33 @@ function getBridge(parentWindow) {
   if (!parent || parent === window) return null;
   return parent.lxpackBridge?.v1 ?? parent.lxpack ?? null;
 }
+function getLxpackBridge(parentWindow, opts) {
+  return getBridge(parentWindow, opts);
+}
 function isDevEnvironment() {
+  try {
+    if (import_meta.env?.DEV === true) return true;
+    if (import_meta.env?.PROD === true) return false;
+  } catch {
+  }
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
-function dispatchBridgeAction(bridge, action) {
+function handleBridgeError(err, onBridgeError) {
+  onBridgeError?.(err);
+  if (isDevEnvironment()) {
+    console.warn(
+      "[lessonkit/lxpack] lxpack bridge action failed:",
+      err instanceof Error ? err.message : err
+    );
+  }
+}
+function dispatchBridgeAction(bridge, action, opts) {
   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
-      );
-    }
+    handleBridgeError(err, opts?.onBridgeError);
   }
 }
 function dispatchBridgeActionInner(bridge, action) {
@@ -132,7 +255,7 @@ function dispatchBridgeActionInner(bridge, action) {
       bridge.completeCourse?.();
       return;
     case "submitAssessment": {
-      const scaled = (0, import_spa_bridge.normalizeScore)({
+      const scaled = normalizeScore({
         score: action.score,
         maxScore: action.maxScore
       });
@@ -140,7 +263,7 @@ function dispatchBridgeActionInner(bridge, action) {
       bridge.submitAssessment?.({
         id: action.id,
         score: scaled,
-        passingScore: (0, import_spa_bridge.normalizePassingThreshold)({
+        passingScore: normalizePassingThreshold({
           passingScore: action.passingScore,
           maxScore: action.maxScore
         }),
@@ -155,13 +278,16 @@ function dispatchBridgeActionInner(bridge, action) {
       return;
   }
 }
-function forwardAssessmentCompletedToBridge(bridge, event) {
+function forwardAssessmentCompletedToBridge(bridge, event, onBridgeMiss) {
   const data = event.data;
   const scaled = normalizeAssessmentScore({
     score: data.score,
     maxScore: data.maxScore
   });
-  if (scaled === null) return;
+  if (scaled === null) {
+    onBridgeMiss?.(event);
+    return;
+  }
   bridge.submitAssessment?.({
     id: data.checkId,
     score: scaled,
@@ -172,50 +298,97 @@ function forwardAssessmentCompletedToBridge(bridge, event) {
     maxScore: data.maxScore
   });
 }
-function forwardTelemetryToBridge(event, mode = "auto", parentWindow) {
+function forwardTelemetryToBridge(event, mode = "auto", parentWindow, opts) {
   if (mode === "off") return;
-  const bridge = getBridge(parentWindow);
+  const bridge = getBridge(parentWindow, {
+    allowedParentOrigins: opts?.allowedParentOrigins,
+    mode
+  });
   if (!bridge) return;
-  if (event.name === "assessment_completed") {
-    forwardAssessmentCompletedToBridge(bridge, event);
-    return;
+  try {
+    if (event.name === "assessment_completed") {
+      forwardAssessmentCompletedToBridge(bridge, event, opts?.onBridgeMiss);
+      return;
+    }
+    const answeredTrack = answeredTelemetryToBridgeTrackEvent(event);
+    if (answeredTrack) {
+      bridge.track?.(answeredTrack);
+      return;
+    }
+    const branchTrack = branchTelemetryToBridgeTrackEvent(event);
+    if (branchTrack) {
+      bridge.track?.(branchTrack);
+      return;
+    }
+    const lessonkitEvent = telemetryEventToLessonkit(event);
+    if (!lessonkitEvent) return;
+    const action = (0, import_tracking_schema3.mapLessonkitTelemetryToBridgeAction)(lessonkitEvent);
+    dispatchBridgeActionInner(bridge, action);
+  } catch (err) {
+    handleBridgeError(err, opts?.onBridgeError);
   }
-  const lessonkitEvent = telemetryEventToLessonkit(event);
-  if (!lessonkitEvent) return;
-  const action = (0, import_tracking_schema3.mapLessonkitTelemetryToBridgeAction)(lessonkitEvent);
-  dispatchBridgeAction(bridge, action);
 }
-function createLxpackBridge() {
-  return getBridge();
+function createLxpackBridge(opts) {
+  return getBridge(void 0, opts);
 }
-function notifyLxpackLessonComplete(lessonId) {
-  const bridge = getBridge();
+function notifyLxpackLessonComplete(lessonId, opts) {
+  const bridge = getBridge(void 0, opts);
   if (!bridge?.completeLesson) return false;
-  bridge.completeLesson(lessonId);
-  return true;
+  try {
+    bridge.completeLesson(lessonId);
+    return true;
+  } catch (err) {
+    handleBridgeError(err, opts?.onBridgeError);
+    return false;
+  }
 }
-function notifyLxpackCourseComplete() {
-  const bridge = getBridge();
+function notifyLxpackCourseComplete(opts) {
+  const bridge = getBridge(void 0, opts);
   if (!bridge?.completeCourse) return false;
-  bridge.completeCourse();
-  return true;
+  try {
+    bridge.completeCourse();
+    return true;
+  } catch (err) {
+    handleBridgeError(err, opts?.onBridgeError);
+    return false;
+  }
 }
-function notifyLxpackAssessment(payload) {
-  const bridge = getBridge();
+function notifyLxpackAssessment(payload, opts) {
+  const bridge = getBridge(void 0, opts);
   if (!bridge?.submitAssessment) return false;
-  bridge.submitAssessment(payload);
-  return true;
+  const scaled = normalizeAssessmentScore({
+    score: payload.score,
+    maxScore: payload.maxScore
+  });
+  if (scaled === null) return false;
+  try {
+    bridge.submitAssessment({
+      ...payload,
+      score: scaled,
+      passingScore: normalizeAssessmentPassingScore({
+        passingScore: payload.passingScore,
+        maxScore: payload.maxScore
+      })
+    });
+    return true;
+  } catch (err) {
+    handleBridgeError(err, opts?.onBridgeError);
+    return false;
+  }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BRANCH_TELEMETRY_EVENTS,
   DEFAULT_BRIDGE_PASSING_SCORE,
   LESSONKIT_TELEMETRY_EVENTS,
   LXPACK_BRIDGE_VERSIONS,
+  branchTelemetryToBridgeTrackEvent,
   createLxpackBridge,
   createLxpackBridgeHost,
   dispatchBridgeAction,
   forwardTelemetryToBridge,
   getLxpackBridge,
+  isParentOriginAllowed,
   mapLessonkitTelemetryToBridgeAction,
   mapLessonkitTelemetryToLxpack,
   normalizeAssessmentPassingScore,
@@ -225,6 +398,7 @@ function notifyLxpackAssessment(payload) {
   notifyLxpackAssessment,
   notifyLxpackCourseComplete,
   notifyLxpackLessonComplete,
+  resolveParentOrigin,
   supportedBridgeVersions,
   telemetryEventToLessonkit
 });

package/dist/bridge.d.cts

@@ -1,9 +1,23 @@
 import { LmsBridgeMode, 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';
+export { DEFAULT_BRIDGE_PASSING_SCORE, LXPACK_BRIDGE_VERSIONS, LxpackBridgeSubmitAssessmentPayload, LxpackBridgeV1, createLxpackBridgeHost, 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';
+export { B as BRANCH_TELEMETRY_EVENTS, b as branchTelemetryToBridgeTrackEvent, t as telemetryEventToLessonkit } from './telemetry-0fIWoomS.cjs';
+
+/**
+ * Scale a raw quiz score to 0–1 for the LXPack parent bridge.
+ * When `maxScore > 1`, always treats `score` as raw points (fixes partial-credit 1/N cases).
+ */
+declare function normalizeScore(raw: {
+    score?: number;
+    maxScore?: number;
+}): number | null;
+/** Scale a raw passing threshold to 0–1 for the LXPack parent bridge. */
+declare function normalizePassingThreshold(raw?: {
+    passingScore?: number;
+    maxScore?: number;
+}): number;
 
 /**
  * Scale a raw quiz score to 0–1 for the LXPack parent bridge.
@@ -15,26 +29,60 @@ declare function normalizeAssessmentScore(opts: {
 }): number | null;
 /**
  * Scale a raw passing threshold to 0–1 for the LXPack parent bridge.
- * Delegates to `@lxpack/spa-bridge` (default 0.7 when omitted).
+ * Default 1.0 (100%) when omitted — matches React SPA default.
  */
 declare function normalizeAssessmentPassingScore(opts?: {
     passingScore?: number;
     maxScore?: number;
 }): number;
+type BridgeAccessOptions = {
+    /** Allowed parent-frame origins (scheme + host + port). When set, bridge calls require a matching origin. */
+    allowedParentOrigins?: string[];
+    /** LMS bridge mode; `"auto"` in production requires `allowedParentOrigins`. */
+    mode?: LxpackBridgeMode;
+    onBridgeError?: (err: unknown) => void;
+};
+/** Resolve the parent frame origin when embedded (same-origin parent or document.referrer fallback). */
+declare function resolveParentOrigin(parentWindow?: Window): string | null;
+/** Returns true when no allowlist is configured or the resolved parent origin is listed. */
+declare function isParentOriginAllowed(allowedParentOrigins: string[] | undefined, parentWindow?: Window, mode?: LxpackBridgeMode): boolean;
+/** Resolve the LXPack parent bridge when the parent origin passes validation. */
+declare function getLxpackBridge(parentWindow?: Window, opts?: BridgeAccessOptions): LxpackBridgeV1 | null;
 /** @deprecated Use `LmsBridgeMode` from `@lessonkit/core`. */
 type LxpackBridgeMode = LmsBridgeMode;
 /** Apply a mapped bridge action to an LXPack bridge instance. */
-declare function dispatchBridgeAction(bridge: LxpackBridgeV1, action: ReturnType<typeof mapLessonkitTelemetryToBridgeAction>): void;
-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;
+declare function dispatchBridgeAction(bridge: LxpackBridgeV1, action: ReturnType<typeof mapLessonkitTelemetryToBridgeAction>, opts?: {
+    onBridgeError?: (err: unknown) => void;
+}): void;
+type ForwardTelemetryToBridgeOptions = {
+    onBridgeError?: (err: unknown) => void;
+    /** Called when assessment_completed cannot be forwarded (e.g. missing/invalid score). */
+    onBridgeMiss?: (event: TelemetryEvent) => void;
+    allowedParentOrigins?: string[];
+};
+/**
+ * Map a LessonKit telemetry event to LMS bridge actions (`track`, `complete`, assessment score).
+ *
+ * @example
+ * ```ts
+ * import { forwardTelemetryToBridge } from "@lessonkit/lxpack/bridge";
+ *
+ * forwardTelemetryToBridge(event, "auto", window.parent, {
+ *   allowedParentOrigins: ["https://lms.example.com"],
+ *   onBridgeMiss: (e) => console.warn("bridge miss", e.name),
+ * });
+ * ```
+ */
+declare function forwardTelemetryToBridge(event: TelemetryEvent, mode?: LxpackBridgeMode, parentWindow?: Window, opts?: ForwardTelemetryToBridgeOptions): void;
+declare function createLxpackBridge(opts?: BridgeAccessOptions): LxpackBridgeV1 | null;
+declare function notifyLxpackLessonComplete(lessonId: LessonId, opts?: BridgeAccessOptions): boolean;
+declare function notifyLxpackCourseComplete(opts?: BridgeAccessOptions): boolean;
 /**
  * Submit assessment results to the parent LXPack bridge.
- * `score` must already be on a 0–1 scale (use `normalizeAssessmentScore` for raw points).
+ * Raw point scores are normalized to 0–1 before submission.
  */
 declare function notifyLxpackAssessment(payload: LxpackBridgeSubmitAssessmentPayload & {
     id: CheckId;
-}): boolean;
+}, opts?: BridgeAccessOptions): boolean;
 
-export { type LxpackBridgeMode, createLxpackBridge, dispatchBridgeAction, forwardTelemetryToBridge, normalizeAssessmentPassingScore, normalizeAssessmentScore, notifyLxpackAssessment, notifyLxpackCourseComplete, notifyLxpackLessonComplete };
+export { type BridgeAccessOptions, type ForwardTelemetryToBridgeOptions, type LxpackBridgeMode, createLxpackBridge, dispatchBridgeAction, forwardTelemetryToBridge, getLxpackBridge, isParentOriginAllowed, normalizeAssessmentPassingScore, normalizeAssessmentScore, normalizePassingThreshold, normalizeScore, notifyLxpackAssessment, notifyLxpackCourseComplete, notifyLxpackLessonComplete, resolveParentOrigin };