@lessonkit/lxpack 1.4.0 → 1.5.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,36 @@ 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) |
 
 ## 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/dist/bridge.cjs

@@ -20,14 +20,17 @@ 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,
@@ -37,6 +40,7 @@ __export(bridge_exports, {
   notifyLxpackAssessment: () => notifyLxpackAssessment,
   notifyLxpackCourseComplete: () => notifyLxpackCourseComplete,
   notifyLxpackLessonComplete: () => notifyLxpackLessonComplete,
+  resolveParentOrigin: () => resolveParentOrigin,
   supportedBridgeVersions: () => import_spa_bridge2.supportedBridgeVersions,
   telemetryEventToLessonkit: () => telemetryEventToLessonkit
 });
@@ -48,43 +52,91 @@ 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 = {};
 function normalizeAssessmentScore(opts) {
   if (typeof opts.score !== "number" || !Number.isFinite(opts.score)) {
     return null;
@@ -97,7 +149,41 @@ function normalizeAssessmentPassingScore(opts) {
     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 {
+    const referrer = typeof document !== "undefined" ? document.referrer : "";
+    if (!referrer) return null;
+    try {
+      return new URL(referrer).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 +191,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) {
@@ -172,50 +270,70 @@ 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);
+      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;
 }
-function notifyLxpackCourseComplete() {
-  const bridge = getBridge();
+function notifyLxpackCourseComplete(opts) {
+  const bridge = getBridge(void 0, opts);
   if (!bridge?.completeCourse) return false;
   bridge.completeCourse();
   return true;
 }
-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;
 }
 // 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 +343,7 @@ function notifyLxpackAssessment(payload) {
   notifyLxpackAssessment,
   notifyLxpackCourseComplete,
   notifyLxpackLessonComplete,
+  resolveParentOrigin,
   supportedBridgeVersions,
   telemetryEventToLessonkit
 });

package/dist/bridge.d.cts

@@ -1,9 +1,9 @@
 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, 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';
+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.
@@ -21,20 +21,38 @@ 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;
+};
+/** 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;
+    allowedParentOrigins?: string[];
+};
+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).
  */
 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, notifyLxpackAssessment, notifyLxpackCourseComplete, notifyLxpackLessonComplete, resolveParentOrigin };

package/dist/bridge.d.ts

@@ -1,9 +1,9 @@
 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, 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';
+export { B as BRANCH_TELEMETRY_EVENTS, b as branchTelemetryToBridgeTrackEvent, t as telemetryEventToLessonkit } from './telemetry-0fIWoomS.js';
 
 /**
  * Scale a raw quiz score to 0–1 for the LXPack parent bridge.
@@ -21,20 +21,38 @@ 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;
+};
+/** 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;
+    allowedParentOrigins?: string[];
+};
+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).
  */
 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, notifyLxpackAssessment, notifyLxpackCourseComplete, notifyLxpackLessonComplete, resolveParentOrigin };