scorm-again 3.0.5 → 3.1.0

package/dist/esm/scorm-again.js

@@ -268,6 +268,15 @@ function parseNavigationRequest(navRequest) {
   };
 }
 
+const appendQueryParam = (url, name, value) => {
+  const fragmentIndex = url.indexOf("#");
+  const baseUrl = fragmentIndex === -1 ? url : url.slice(0, fragmentIndex);
+  const fragment = fragmentIndex === -1 ? "" : url.slice(fragmentIndex);
+  const separator = baseUrl.includes("?") ? baseUrl.endsWith("?") || baseUrl.endsWith("&") ? "" : "&" : "?";
+  const queryParam = `${encodeURIComponent(name)}=${encodeURIComponent(String(value))}`;
+  return `${baseUrl}${separator}${queryParam}${fragment}`;
+};
+
 class BaseCMI {
   /**
    * Flag used during JSON serialization to allow getter access without initialization checks.
@@ -659,7 +668,10 @@ const scorm12_errors = {
   READ_ONLY_ELEMENT: 403,
   WRITE_ONLY_ELEMENT: 404,
   TYPE_MISMATCH: 405,
-  VALUE_OUT_OF_RANGE: 407,
+  // SCORM 1.2 has no out-of-range error code; an out-of-range value is reported
+  // as 405 (incorrect data type), per the SCORM 1.2 RTE error table and the ADL
+  // 1.2 CTS (DataModelValidator.checkScoreDecimal failure -> CMICategory 405).
+  VALUE_OUT_OF_RANGE: 405,
   DEPENDENCY_NOT_ESTABLISHED: 408
 };
 const scorm2004_errors = {
@@ -807,6 +819,7 @@ const DefaultSettings = {
   xhrWithCredentials: false,
   fetchMode: "cors",
   asyncModeBeaconBehavior: "never",
+  includeCommitSequence: false,
   responseHandler: async function(response) {
     if (typeof response !== "undefined") {
       let httpResult = null;
@@ -1739,7 +1752,7 @@ class ScheduledCommit {
   wrapper() {
     if (!this._cancelled) {
       if (this._API.isInitialized()) {
-        (async () => await this._API.commit(this._callback))();
+        (async () => await this._API.commit(this._callback, false, "autocommit"))();
       }
     }
   }
@@ -5084,6 +5097,7 @@ class ActivityDeliveryService {
 }
 
 class AsynchronousHttpService {
+  reportsRequestCompletion = true;
   settings;
   error_codes;
   /**
@@ -5108,10 +5122,20 @@ class AsynchronousHttpService {
    * @param {boolean} immediate - Whether to send the request immediately without waiting
    * @param {Function} apiLog - Function to log API messages with appropriate levels
    * @param {Function} processListeners - Function to trigger event listeners for commit events
+   * @param {CommitMetadata} metadata - Metadata describing the captured commit
+   * @param {Function} onRequestComplete - Callback invoked after the background request settles
    * @return {ResultObject} - Immediate optimistic success result
    */
-  processHttpRequest(url, params, immediate = false, apiLog, processListeners) {
-    this._performAsyncRequest(url, params, immediate, apiLog, processListeners);
+  processHttpRequest(url, params, immediate = false, apiLog, processListeners, metadata, onRequestComplete) {
+    this._performAsyncRequest(
+      url,
+      params,
+      immediate,
+      apiLog,
+      processListeners,
+      metadata,
+      onRequestComplete
+    );
     return {
       result: global_constants.SCORM_TRUE,
       errorCode: 0
@@ -5124,11 +5148,14 @@ class AsynchronousHttpService {
    * @param {boolean} immediate - Whether this is an immediate request
    * @param apiLog - Function to log API messages
    * @param {Function} processListeners - Function to process event listeners
+   * @param {CommitMetadata} metadata - Metadata describing the captured commit
+   * @param {Function} onRequestComplete - Callback invoked after the request settles
    * @private
    */
-  async _performAsyncRequest(url, params, immediate, apiLog, processListeners) {
+  async _performAsyncRequest(url, params, immediate, apiLog, processListeners, metadata, onRequestComplete) {
     try {
-      const processedParams = this.settings.requestHandler(params);
+      const handledParams = metadata === void 0 ? this.settings.requestHandler(params) : this.settings.requestHandler(params, metadata);
+      const processedParams = handledParams;
       let response;
       if (immediate && this.settings.asyncModeBeaconBehavior !== "never") {
         response = await this.performBeacon(url, processedParams);
@@ -5144,7 +5171,9 @@ class AsynchronousHttpService {
     } catch (e) {
       const message = e instanceof Error ? e.message : String(e);
       apiLog("processHttpRequest", `Async request failed: ${message}`, LogLevelEnum.ERROR);
-      processListeners("CommitError");
+      processListeners("CommitError", void 0, this.error_codes.GENERAL_COMMIT_FAILURE || 391);
+    } finally {
+      onRequestComplete?.();
     }
   }
   /**
@@ -5287,10 +5316,13 @@ class CMIValueAccessService {
   }
   /**
    * Gets the appropriate error code for undefined data model elements.
-   * SCORM 2004 uses UNDEFINED_DATA_MODEL, SCORM 1.2 uses GENERAL.
+   * Both SCORM 2004 and SCORM 1.2 use UNDEFINED_DATA_MODEL (401): an
+   * unrecognized element is "Not implemented", not a general exception. SCORM
+   * 1.2 previously returned GENERAL (101) here, which is non-conformant — the
+   * ADL 1.2 CTS and the SCORM 1.2 RTE spec expect 401 for an unknown element.
    */
-  getUndefinedDataModelErrorCode(scorm2004) {
-    return scorm2004 ? getErrorCode(this.context.errorCodes, "UNDEFINED_DATA_MODEL") : getErrorCode(this.context.errorCodes, "GENERAL");
+  getUndefinedDataModelErrorCode() {
+    return getErrorCode(this.context.errorCodes, "UNDEFINED_DATA_MODEL");
   }
   /**
    * Sets a value on a CMI element path
@@ -5318,7 +5350,7 @@ class CMIValueAccessService {
     let returnValue = global_constants.SCORM_FALSE;
     let foundFirstIndex = false;
     const invalidErrorMessage = `The data model element passed to ${methodName} (${CMIElement}) is not a valid SCORM data model element.`;
-    const invalidErrorCode = this.getUndefinedDataModelErrorCode(scorm2004);
+    const invalidErrorCode = this.getUndefinedDataModelErrorCode();
     for (let idx = 0; idx < structure.length; idx++) {
       const attribute = structure[idx];
       if (idx === structure.length - 1) {
@@ -5388,12 +5420,13 @@ class CMIValueAccessService {
       );
       return "";
     }
+    this.context.setLastErrorCode("0");
     const structure = CMIElement.split(".");
     let refObject = this.context.getDataModel();
     let attribute = null;
     const uninitializedErrorMessage = `The data model element passed to ${methodName} (${CMIElement}) has not been initialized.`;
     const invalidErrorMessage = `The data model element passed to ${methodName} (${CMIElement}) is not a valid SCORM data model element.`;
-    const invalidErrorCode = this.getUndefinedDataModelErrorCode(scorm2004);
+    const invalidErrorCode = this.getUndefinedDataModelErrorCode();
     for (let idx = 0; idx < structure.length; idx++) {
       attribute = structure[idx];
       const validationResult = this.validateGetAttribute(
@@ -6105,8 +6138,9 @@ class EventService {
    * @param {string} functionName - The name of the function that triggered the event
    * @param {string} CMIElement - The CMI element that was affected
    * @param {any} value - The value that was set
+   * @param {CommitEventContext} context - Optional context for commit lifecycle events
    */
-  processListeners(functionName, CMIElement, value) {
+  processListeners(functionName, CMIElement, value, context) {
     this.apiLog(functionName, value, LogLevelEnum.INFO, CMIElement);
     const listeners = this.listenerMap.get(functionName);
     if (!listeners) return;
@@ -6131,9 +6165,17 @@ class EventService {
         if (functionName.startsWith("Sequence")) {
           listener.callback(value);
         } else if (functionName === "CommitError") {
-          listener.callback(value);
+          if (context !== void 0) {
+            listener.callback(value, context);
+          } else {
+            listener.callback(value);
+          }
         } else if (functionName === "CommitSuccess") {
-          listener.callback();
+          if (context !== void 0) {
+            listener.callback(context);
+          } else {
+            listener.callback();
+          }
         } else {
           listener.callback(CMIElement, value);
         }
@@ -6267,16 +6309,19 @@ class OfflineStorageService {
    * Store commit data offline
    * @param {string} courseId - Identifier for the course
    * @param {CommitObject} commitData - The data to store offline
+   * @param {OfflineCommitMetadata} metadata - Metadata captured with the original commit
    * @returns {ResultObject} - Result of the storage operation
    */
-  storeOffline(courseId, commitData) {
+  storeOffline(courseId, commitData, metadata) {
     try {
       const queueItem = {
         id: `${courseId}_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`,
         courseId,
         timestamp: Date.now(),
         data: commitData,
-        syncAttempts: 0
+        syncAttempts: 0,
+        ...metadata?.isTerminateCommit !== void 0 ? { isTerminateCommit: metadata.isTerminateCommit } : {},
+        ...metadata?.sequence !== void 0 ? { sequence: metadata.sequence } : {}
       };
       const currentQueue = this.getFromStorage(this.syncQueue) || [];
       currentQueue.push(queueItem);
@@ -6355,7 +6400,10 @@ class OfflineStorageService {
           continue;
         }
         try {
-          const syncResult = await this.sendDataToLMS(item.data);
+          const syncResult = await this.sendDataToLMS(item.data, {
+            ...item.isTerminateCommit !== void 0 ? { isTerminateCommit: item.isTerminateCommit } : {},
+            ...item.sequence !== void 0 ? { sequence: item.sequence } : {}
+          });
           if (syncResult.result === true || syncResult.result === global_constants.SCORM_TRUE) {
             this.apiLog(
               "OfflineStorageService",
@@ -6402,17 +6450,25 @@ class OfflineStorageService {
   /**
    * Send data to the LMS when online
    * @param {CommitObject} data - The data to send to the LMS
+   * @param {OfflineCommitMetadata} metadata - Metadata captured with the original commit
    * @returns {Promise<ResultObject>} - Result of the sync operation
    */
-  async sendDataToLMS(data) {
-    if (!this.settings.lmsCommitUrl) {
+  async sendDataToLMS(data, metadata) {
+    const configuredCommitUrl = this.settings.lmsCommitUrl;
+    if (!configuredCommitUrl) {
       return {
         result: global_constants.SCORM_FALSE,
         errorCode: this.error_codes.GENERAL || 101
       };
     }
     try {
-      const processedData = this.settings.requestHandler(data);
+      const lmsCommitUrl = String(configuredCommitUrl);
+      const processedData = this.settings.requestHandler(data, {
+        isTerminateCommit: metadata?.isTerminateCommit ?? false,
+        trigger: "offline-replay",
+        ...metadata?.sequence !== void 0 ? { sequence: metadata.sequence } : {}
+      });
+      const requestUrl = metadata?.isTerminateCommit && this.settings.terminateCommitParam ? appendQueryParam(lmsCommitUrl, this.settings.terminateCommitParam, "true") : lmsCommitUrl;
       const init = {
         method: "POST",
         mode: this.settings.fetchMode,
@@ -6425,7 +6481,7 @@ class OfflineStorageService {
       if (this.settings.xhrWithCredentials) {
         init.credentials = "include";
       }
-      const response = await fetch(this.settings.lmsCommitUrl, init);
+      const response = await fetch(requestUrl, init);
       const result = typeof this.settings.responseHandler === "function" ? await this.settings.responseHandler(response) : await response.json();
       if (response.status >= 200 && response.status <= 299 && (result.result === true || result.result === global_constants.SCORM_TRUE)) {
         if (!Object.hasOwnProperty.call(result, "errorCode")) {
@@ -15390,6 +15446,8 @@ class SynchronousHttpService {
    * @param {boolean} immediate - Whether this is a termination commit (use sendBeacon)
    * @param {Function} _apiLog - Function to log API messages (unused in synchronous mode - errors returned directly)
    * @param {Function} _processListeners - Function to trigger event listeners (unused in synchronous mode - no async events)
+   * @param {CommitMetadata} metadata - Metadata describing the captured commit
+   * @param {Function} _onRequestComplete - Completion callback (unused because requests settle before return)
    * @return {ResultObject} - The result of the request (synchronous)
    *
    * @remarks
@@ -15399,21 +15457,23 @@ class SynchronousHttpService {
    * - No async events need to be triggered (CommitSuccess/CommitError) since results are synchronous
    * - AsynchronousHttpService uses these parameters to handle background request results
    */
-  processHttpRequest(url, params, immediate = false, _apiLog, _processListeners) {
+  processHttpRequest(url, params, immediate = false, _apiLog, _processListeners, metadata, _onRequestComplete) {
     if (immediate) {
-      return this._handleImmediateRequest(url, params);
+      return this._handleImmediateRequest(url, params, metadata);
     }
-    return this._performSyncXHR(url, params);
+    return this._performSyncXHR(url, params, metadata);
   }
   /**
    * Handles an immediate request using sendBeacon
    * @param {string} url - The URL to send the request to
    * @param {CommitObject|StringKeyMap|Array} params - The parameters to include in the request
+   * @param {CommitMetadata} metadata - Metadata describing the captured commit
    * @return {ResultObject} - The result based on beacon success
    * @private
    */
-  _handleImmediateRequest(url, params) {
-    const requestPayload = this.settings.requestHandler(params) ?? params;
+  _handleImmediateRequest(url, params, metadata) {
+    const handledPayload = metadata === void 0 ? this.settings.requestHandler(params) : this.settings.requestHandler(params, metadata);
+    const requestPayload = handledPayload ?? params;
     const { body } = this._prepareRequestBody(requestPayload);
     const beaconSuccess = navigator.sendBeacon(
       url,
@@ -15428,11 +15488,13 @@ class SynchronousHttpService {
    * Performs a synchronous XMLHttpRequest
    * @param {string} url - The URL to send the request to
    * @param {CommitObject|StringKeyMap|Array} params - The parameters to include in the request
+   * @param {CommitMetadata} metadata - Metadata describing the captured commit
    * @return {ResultObject} - The result of the request
    * @private
    */
-  _performSyncXHR(url, params) {
-    const requestPayload = this.settings.requestHandler(params) ?? params;
+  _performSyncXHR(url, params, metadata) {
+    const handledPayload = metadata === void 0 ? this.settings.requestHandler(params) : this.settings.requestHandler(params, metadata);
+    const requestPayload = handledPayload ?? params;
     const { body, contentType } = this._prepareRequestBody(requestPayload);
     const xhr = new XMLHttpRequest();
     xhr.open("POST", url, false);
@@ -15511,9 +15573,15 @@ class ValidationService {
    * @param {number} invalidTypeCode - The error code for invalid type
    * @param {number} invalidRangeCode - The error code for invalid range
    * @param {typeof BaseScormValidationError} errorClass - The error class to use for validation errors
+   * @param {boolean} allowEmptyString - When true, an empty string is accepted (clears the value).
+   *                                     SCORM 1.2 score elements may be blank per the ADL 1.2 CTS
+   *                                     (DataModelValidator.checkScoreDecimal treats blank as valid).
    * @return {boolean} - True if validation passes, throws an error otherwise
    */
-  validateScore(CMIElement, value, decimalRegex, scoreRange, invalidTypeCode, invalidRangeCode, errorClass) {
+  validateScore(CMIElement, value, decimalRegex, scoreRange, invalidTypeCode, invalidRangeCode, errorClass, allowEmptyString = false) {
+    if (allowEmptyString && value === "") {
+      return true;
+    }
     return checkValidFormat(CMIElement, value, decimalRegex, invalidTypeCode, errorClass) && (!scoreRange || checkValidRange(CMIElement, value, scoreRange, invalidRangeCode, errorClass));
   }
   /**
@@ -15587,6 +15655,21 @@ class BaseAPI {
   _offlineStorageService;
   _cmiValueAccessService;
   _courseId = "";
+  _pendingCommitCount = 0;
+  /**
+   * Monotonic sequence for commits captured by this API instance. It is
+   * intentionally not reset by reset().
+   */
+  _commitSequence = 0;
+  _commitSettleWaiters = [];
+  /**
+   * Canonical paths of every CMI element that has been explicitly assigned a
+   * value via SetValue / loadFromJSON (both funnel through _commonSetCMIValue).
+   * Used by standards that must tell "implemented but never set" apart from a
+   * legitimately empty value when answering GetValue (SCORM 2004 error 403).
+   * Cleared on reset so a fresh SCO attempt starts with nothing "set".
+   */
+  _setCMIElements = /* @__PURE__ */ new Set();
   /**
    * Constructor for Base API class. Sets some shared API fields, as well as
    * sets up options for the API.
@@ -15772,6 +15855,7 @@ class BaseAPI {
     this.lastErrorCode = "0";
     this._eventService.reset();
     this.startingData = {};
+    this._setCMIElements.clear();
     if (this._offlineStorageService) {
       this._offlineStorageService.updateSettings(this.settings);
       if (settings?.courseId) {
@@ -15856,6 +15940,52 @@ class BaseAPI {
       this._loggingService?.setLogHandler(settings.onLogMessage);
     }
   }
+  /**
+   * Gets the number of captured commit requests that have not yet settled.
+   *
+   * @return {number} The number of in-flight commits
+   */
+  get pendingCommitCount() {
+    return this._pendingCommitCount;
+  }
+  /**
+   * Resolves when all currently in-flight commits have settled. A timeout is
+   * best-effort: the promise resolves when it elapses even if commits remain,
+   * and callers can inspect pendingCommitCount afterward to detect that case.
+   *
+   * @param {Object} [options] - Settle options
+   * @param {number} [options.timeoutMs] - Maximum time to wait in milliseconds
+   * @return {Promise<void>} A promise that resolves after the drain or timeout
+   */
+  whenCommitsSettled(options) {
+    if (this._pendingCommitCount === 0) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      const waiter = { resolve };
+      if (options?.timeoutMs !== void 0) {
+        waiter.timeoutId = setTimeout(() => {
+          const waiterIndex = this._commitSettleWaiters.indexOf(waiter);
+          if (waiterIndex === -1) {
+            return;
+          }
+          this._commitSettleWaiters.splice(waiterIndex, 1);
+          resolve();
+        }, options.timeoutMs);
+      }
+      this._commitSettleWaiters.push(waiter);
+    });
+  }
+  /** Resolve and clear every waiter after the pending count reaches zero. */
+  _flushCommitSettleWaiters() {
+    const waiters = this._commitSettleWaiters.splice(0);
+    for (const waiter of waiters) {
+      if (waiter.timeoutId !== void 0) {
+        clearTimeout(waiter.timeoutId);
+      }
+      waiter.resolve();
+    }
+  }
   /**
    * Terminates the current run of the API
    * @param {string} callbackName
@@ -15876,7 +16006,7 @@ class BaseAPI {
     } else {
       stateCheckPassed = true;
       this.processListeners("BeforeTerminate");
-      const result = this.storeData(true);
+      const result = this.storeData(true, "terminate");
       if ((result.errorCode ?? 0) > 0) {
         if (result.errorMessage) {
           this.apiLog(
@@ -15928,6 +16058,9 @@ class BaseAPI {
       } catch (e) {
         returnValue = this.handleValueAccessException(CMIElement, e, returnValue);
       }
+      if (this.lastErrorCode === "0") {
+        this.checkUninitializedGet(CMIElement, returnValue);
+      }
       this.processListeners(callbackName, CMIElement);
     }
     this.apiLog(callbackName, ": returned: " + returnValue, LogLevelEnum.INFO, CMIElement);
@@ -15937,6 +16070,10 @@ class BaseAPI {
     if (this.lastErrorCode === "0") {
       this.clearSCORMError(returnValue);
     }
+    const rawReturn = returnValue;
+    if (typeof rawReturn === "number" || typeof rawReturn === "boolean") {
+      return String(rawReturn);
+    }
     return returnValue;
   }
   /**
@@ -15989,9 +16126,10 @@ class BaseAPI {
    * Orders LMS to store all content parameters
    * @param {string} callbackName
    * @param {boolean} checkTerminated
+   * @param {CommitTrigger} trigger - What initiated the commit
    * @return {string}
    */
-  commit(callbackName, checkTerminated = false) {
+  commit(callbackName, checkTerminated = false, trigger = "manual") {
     this.clearScheduledCommit();
     let returnValue = global_constants.SCORM_TRUE;
     if (this.isNotInitialized()) {
@@ -16003,7 +16141,7 @@ class BaseAPI {
       this.throwSCORMError("api", errorCode);
       if (errorCode === 143) returnValue = global_constants.SCORM_FALSE;
     } else {
-      const result = this.storeData(false);
+      const result = this.storeData(false, trigger);
       const errorCode = result.errorCode ?? 0;
       if (errorCode > 0) {
         if (result.errorMessage) {
@@ -16234,7 +16372,16 @@ class BaseAPI {
    * @return {string}
    */
   _commonSetCMIValue(methodName, scorm2004, CMIElement, value) {
-    return this._cmiValueAccessService.setCMIValue(methodName, scorm2004, CMIElement, value);
+    const result = this._cmiValueAccessService.setCMIValue(
+      methodName,
+      scorm2004,
+      CMIElement,
+      value
+    );
+    if (result === global_constants.SCORM_TRUE) {
+      this._setCMIElements.add(CMIElement);
+    }
+    return result;
   }
   /**
    * Gets a value from the CMI Object.
@@ -16248,6 +16395,18 @@ class BaseAPI {
   _commonGetCMIValue(methodName, scorm2004, CMIElement) {
     return this._cmiValueAccessService.getCMIValue(methodName, scorm2004, CMIElement);
   }
+  /**
+   * Hook invoked by getValue after a successful resolution. Standards that must
+   * distinguish "implemented but never set, no default value" from a
+   * legitimately empty value override this to raise VALUE_NOT_INITIALIZED.
+   * Default is a no-op, so SCORM 1.2 / AICC keep returning "" with code 0.
+   *
+   * @param {string} _CMIElement - the element that was read
+   * @param {any} _returnValue - the value getCMIValue resolved
+   * @protected
+   */
+  checkUninitializedGet(_CMIElement, _returnValue) {
+  }
   /**
    * Returns true if the API's current state is STATE_INITIALIZED
    *
@@ -16330,9 +16489,14 @@ class BaseAPI {
    * @param {string} functionName - The name of the function/event that occurred
    * @param {string} CMIElement - Optional CMI element involved in the event
    * @param {any} value - Optional value associated with the event
+   * @param {CommitEventContext} context - Optional context for commit lifecycle events
    */
-  processListeners(functionName, CMIElement, value) {
-    this._eventService.processListeners(functionName, CMIElement, value);
+  processListeners(functionName, CMIElement, value, context) {
+    if (context !== void 0) {
+      this._eventService.processListeners(functionName, CMIElement, value, context);
+    } else {
+      this._eventService.processListeners(functionName, CMIElement, value);
+    }
   }
   /**
    * Throws a SCORM error with the specified error number and optional message.
@@ -16465,36 +16629,106 @@ class BaseAPI {
    * @param {string} url - The URL to send the request to
    * @param {CommitObject | StringKeyMap | Array<any>} params - The parameters to send
    * @param {boolean} immediate - Whether to send the request immediately without waiting
+   * @param {CommitTrigger} [trigger] - What initiated the commit
    * @returns {ResultObject} - The result of the request
    */
-  processHttpRequest(url, params, immediate = false) {
-    if (this.settings.enableOfflineSupport && this._offlineStorageService && !this._offlineStorageService.isDeviceOnline() && this._courseId) {
-      this.apiLog(
-        "processHttpRequest",
-        "Device is offline, storing data locally",
-        LogLevelEnum.INFO
-      );
-      if (params && typeof params === "object" && "cmi" in params) {
-        return this._offlineStorageService.storeOffline(this._courseId, params);
-      } else {
+  processHttpRequest(url, params, immediate = false, trigger) {
+    const sequence = ++this._commitSequence;
+    this._pendingCommitCount += 1;
+    let settled = false;
+    let completionDeferred = false;
+    const settle = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      this._pendingCommitCount -= 1;
+      if (this._pendingCommitCount === 0) {
+        this._flushCommitSettleWaiters();
+      }
+    };
+    try {
+      const resolvedTrigger = trigger ?? (immediate ? "terminate" : "manual");
+      let finalParams = params;
+      if (immediate && this.settings.terminateCommitPayloadField) {
+        const field = this.settings.terminateCommitPayloadField;
+        if (Array.isArray(finalParams)) {
+          finalParams = [...finalParams, `${encodeURIComponent(field)}=true`];
+        } else if (finalParams && typeof finalParams === "object") {
+          finalParams = { ...finalParams, [field]: true };
+        }
+      }
+      if (this.settings.includeCommitSequence === true) {
+        if (Array.isArray(finalParams)) {
+          finalParams = [...finalParams, `commitSequence=${sequence}`];
+        } else if (finalParams && typeof finalParams === "object") {
+          finalParams = { ...finalParams, commitSequence: sequence };
+        }
+      }
+      const finalUrl = immediate && this.settings.terminateCommitParam ? appendQueryParam(url, this.settings.terminateCommitParam, "true") : url;
+      const metadata = {
+        isTerminateCommit: immediate,
+        trigger: resolvedTrigger,
+        sequence
+      };
+      const context = {
+        url: finalUrl,
+        trigger: resolvedTrigger,
+        isTerminateCommit: immediate,
+        sequence
+      };
+      if (this.settings.enableOfflineSupport && this._offlineStorageService && !this._offlineStorageService.isDeviceOnline() && this._courseId) {
         this.apiLog(
           "processHttpRequest",
-          "Invalid commit data format for offline storage",
-          LogLevelEnum.ERROR
+          "Device is offline, storing data locally",
+          LogLevelEnum.INFO
         );
-        return {
-          result: global_constants.SCORM_FALSE,
-          errorCode: this._error_codes.GENERAL ?? 101
-        };
+        if (finalParams && typeof finalParams === "object" && "cmi" in finalParams) {
+          return this._offlineStorageService.storeOffline(
+            this._courseId,
+            finalParams,
+            { isTerminateCommit: immediate, sequence }
+          );
+        } else {
+          this.apiLog(
+            "processHttpRequest",
+            "Invalid commit data format for offline storage",
+            LogLevelEnum.ERROR
+          );
+          return {
+            result: global_constants.SCORM_FALSE,
+            errorCode: this._error_codes.GENERAL ?? 101
+          };
+        }
+      }
+      const apiLog = (functionName, message, level, element) => this.apiLog(functionName, message, level, element);
+      const processListeners = (functionName, CMIElement, value) => {
+        if (functionName === "CommitSuccess" || functionName === "CommitError") {
+          if (functionName === "CommitError" && typeof value === "number") {
+            context.errorCode = value;
+          }
+          settle();
+          this.processListeners(functionName, CMIElement, value, context);
+        } else {
+          this.processListeners(functionName, CMIElement, value);
+        }
+      };
+      const result = this._httpService.processHttpRequest(
+        finalUrl,
+        finalParams,
+        immediate,
+        apiLog,
+        processListeners,
+        metadata,
+        settle
+      );
+      completionDeferred = this._httpService.reportsRequestCompletion === true;
+      return result;
+    } finally {
+      if (!completionDeferred) {
+        settle();
       }
     }
-    return this._httpService.processHttpRequest(
-      url,
-      params,
-      immediate,
-      (functionName, message, level, element) => this.apiLog(functionName, message, level, element),
-      (functionName, CMIElement, value) => this.processListeners(functionName, CMIElement, value)
-    );
   }
   /**
    * Schedules a commit operation to occur after a specified delay.
@@ -16654,6 +16888,11 @@ class CMIScore extends BaseCMI {
   __invalid_range_code;
   __decimal_regex;
   __error_class;
+  /**
+   * When true, an empty string is a valid value (clears the element). SCORM 1.2
+   * score elements may be blank per the ADL 1.2 CTS; SCORM 2004 leaves this off.
+   */
+  __allow_empty_string;
   _raw = "";
   _min = "";
   _max;
@@ -16688,6 +16927,7 @@ class CMIScore extends BaseCMI {
     this.__invalid_range_code = params.invalidRangeCode || scorm12_errors.VALUE_OUT_OF_RANGE;
     this.__decimal_regex = params.decimalRegex || scorm12_regex.CMIDecimal;
     this.__error_class = params.errorClass;
+    this.__allow_empty_string = params.allowEmptyString ?? false;
   }
   /**
    * Called when the API has been reset
@@ -16734,7 +16974,8 @@ class CMIScore extends BaseCMI {
       this.__score_range,
       this.__invalid_type_code,
       this.__invalid_range_code,
-      this.__error_class
+      this.__error_class,
+      this.__allow_empty_string
     )) {
       this._raw = raw;
     }
@@ -16758,7 +16999,8 @@ class CMIScore extends BaseCMI {
       this.__score_range,
       this.__invalid_type_code,
       this.__invalid_range_code,
-      this.__error_class
+      this.__error_class,
+      this.__allow_empty_string
     )) {
       this._min = min;
     }
@@ -16782,7 +17024,8 @@ class CMIScore extends BaseCMI {
       this.__score_range,
       this.__invalid_type_code,
       this.__invalid_range_code,
-      this.__error_class
+      this.__error_class,
+      this.__allow_empty_string
     )) {
       this._max = max;
     }
@@ -16839,7 +17082,9 @@ class CMICore extends BaseCMI {
       invalidErrorCode: scorm12_errors.INVALID_SET_VALUE,
       invalidTypeCode: scorm12_errors.TYPE_MISMATCH,
       invalidRangeCode: scorm12_errors.VALUE_OUT_OF_RANGE,
-      errorClass: Scorm12ValidationError
+      errorClass: Scorm12ValidationError,
+      // SCORM 1.2 score elements may be set blank (clears the value), per ADL 1.2 CTS.
+      allowEmptyString: true
     });
   }
   score;
@@ -17269,7 +17514,9 @@ let CMIObjectivesObject$1 = class CMIObjectivesObject extends BaseCMI {
       invalidErrorCode: scorm12_errors.INVALID_SET_VALUE,
       invalidTypeCode: scorm12_errors.TYPE_MISMATCH,
       invalidRangeCode: scorm12_errors.VALUE_OUT_OF_RANGE,
-      errorClass: Scorm12ValidationError
+      errorClass: Scorm12ValidationError,
+      // SCORM 1.2 score elements may be set blank (clears the value), per ADL 1.2 CTS.
+      allowEmptyString: true
     });
   }
   score;
@@ -18739,16 +18986,17 @@ class Scorm12API extends BaseAPI {
    * Attempts to store the data to the LMS
    *
    * @param {boolean} terminateCommit
+   * @param {CommitTrigger} [trigger] - What initiated the commit
    * @return {ResultObject}
    */
-  storeData(terminateCommit) {
+  storeData(terminateCommit, trigger) {
     if (terminateCommit) {
       const originalStatus = this.cmi.core.lesson_status;
       if (this.cmi.core.lesson_mode === "browse") {
         const startingStatus = this.startingData?.cmi?.core?.lesson_status || "";
         if (startingStatus === "" && originalStatus === "not attempted") {
           this.cmi.core.lesson_status = "browsed";
-          return this.processCommitData(terminateCommit);
+          return this.processCommitData(terminateCommit, trigger);
         }
       }
       if (!this.cmi.core.lesson_status || !this.statusSetByModule && this.cmi.core.lesson_status === "not attempted") {
@@ -18777,12 +19025,17 @@ class Scorm12API extends BaseAPI {
         }
       }
     }
-    return this.processCommitData(terminateCommit);
+    return this.processCommitData(terminateCommit, trigger);
   }
-  processCommitData(terminateCommit) {
+  processCommitData(terminateCommit, trigger) {
     const commitObject = this.getCommitObject(terminateCommit);
     if (typeof this.settings.lmsCommitUrl === "string") {
-      return this.processHttpRequest(this.settings.lmsCommitUrl, commitObject, terminateCommit);
+      return this.processHttpRequest(
+        this.settings.lmsCommitUrl,
+        commitObject,
+        terminateCommit,
+        trigger
+      );
     } else {
       return {
         result: global_constants.SCORM_TRUE,
@@ -24366,6 +24619,35 @@ class Scorm2004DataSerializer {
   }
 }
 
+const NO_DEFAULT_2004_ELEMENTS = /* @__PURE__ */ new Set([
+  "cmi.suspend_data",
+  "cmi.location",
+  "cmi.scaled_passing_score",
+  "cmi.max_time_allowed",
+  "cmi.completion_threshold",
+  "cmi.progress_measure",
+  "cmi.score.scaled",
+  "cmi.score.raw",
+  "cmi.score.min",
+  "cmi.score.max",
+  "cmi.objectives.N.score.scaled",
+  "cmi.objectives.N.score.raw",
+  "cmi.objectives.N.score.min",
+  "cmi.objectives.N.score.max",
+  "cmi.objectives.N.progress_measure",
+  "cmi.objectives.N.description",
+  "cmi.interactions.N.weighting",
+  "cmi.interactions.N.type",
+  "cmi.interactions.N.timestamp",
+  "cmi.interactions.N.result",
+  "cmi.interactions.N.latency",
+  "cmi.interactions.N.learner_response",
+  "cmi.interactions.N.description",
+  "cmi.comments_from_learner.N.timestamp"
+]);
+function normalizeCMIIndices(CMIElement) {
+  return CMIElement.replace(/\.\d+(?=\.|$)/g, ".N");
+}
 class Scorm2004API extends BaseAPI {
   _version = "1.0";
   _sequencing;
@@ -24891,6 +25173,39 @@ class Scorm2004API extends BaseAPI {
   getCMIValue(CMIElement) {
     return this._commonGetCMIValue("GetValue", true, CMIElement);
   }
+  /**
+   * Raises 403 (VALUE_NOT_INITIALIZED) when an implemented, no-default element is
+   * read before it has ever been set, per IEEE 1484.11.2 / SCORM 2004 RTE.
+   *
+   * Invoked by BaseAPI.getValue after an otherwise-successful resolution, so it
+   * only sees values the data model already returned cleanly. The decision is
+   * deliberately gated to this public boundary (never the getters) to keep
+   * serialization/commit/rollup — which read the getters directly — unaffected.
+   *
+   * A 403 is raised only when all hold:
+   *  - the resolved value is "" — any non-empty value is by definition set,
+   *    including values written by internal sequencing/activity-tree paths that
+   *    bypass _commonSetCMIValue (those only ever write non-empty values);
+   *  - the element was never set — _setCMIElements records every successful
+   *    SetValue, loadFromJSON, and global-objective restore (all route through
+   *    _commonSetCMIValue), so an explicit SetValue(x, "") still reads back as
+   *    "" with code 0; and
+   *  - the element has no spec-defined default ({@link NO_DEFAULT_2004_ELEMENTS}).
+   *
+   * @param {string} CMIElement
+   * @param {*} returnValue - the value getCMIValue resolved
+   * @protected
+   */
+  checkUninitializedGet(CMIElement, returnValue) {
+    if (returnValue !== "") return;
+    if (this._setCMIElements.has(CMIElement)) return;
+    if (!NO_DEFAULT_2004_ELEMENTS.has(normalizeCMIIndices(CMIElement))) return;
+    this.throwSCORMError(
+      CMIElement,
+      this._error_codes.VALUE_NOT_INITIALIZED ?? 403,
+      `The data model element passed to GetValue (${CMIElement}) has not been initialized.`
+    );
+  }
   /**
    * Returns the message that corresponds to errorNumber.
    * @param {(string|number)} errorNumber
@@ -24937,9 +25252,10 @@ class Scorm2004API extends BaseAPI {
   /**
    * Attempts to store the data to the LMS
    * @param {boolean} terminateCommit
+   * @param {CommitTrigger} [trigger] - What initiated the commit
    * @return {ResultObject}
    */
-  storeData(terminateCommit) {
+  storeData(terminateCommit, trigger) {
     if (terminateCommit) {
       if (this.cmi.mode === "normal") {
         if (this.cmi.credit === "credit") {
@@ -24987,7 +25303,8 @@ class Scorm2004API extends BaseAPI {
       const result = this.processHttpRequest(
         this.settings.lmsCommitUrl,
         commitObject,
-        terminateCommit
+        terminateCommit,
+        trigger
       );
       if (navRequest && result.navRequest !== void 0 && result.navRequest !== "" && typeof result.navRequest === "string") {
         const parsed = parseNavigationRequest(result.navRequest);