scorm-again 3.0.4 → 3.1.0

package/dist/esm/scorm12.js

@@ -161,6 +161,15 @@ function memoize(fn, keyFn) {
   });
 }
 
+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.
@@ -408,7 +417,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
 };
 
@@ -523,6 +535,7 @@ const DefaultSettings = {
   xhrWithCredentials: false,
   fetchMode: "cors",
   asyncModeBeaconBehavior: "never",
+  includeCommitSequence: false,
   responseHandler: async function(response) {
     if (typeof response !== "undefined") {
       let httpResult = null;
@@ -907,13 +920,14 @@ 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"))();
       }
     }
   }
 }
 
 class AsynchronousHttpService {
+  reportsRequestCompletion = true;
   settings;
   error_codes;
   /**
@@ -938,10 +952,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
@@ -954,11 +978,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);
@@ -974,7 +1001,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?.();
     }
   }
   /**
@@ -1117,10 +1146,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
@@ -1148,7 +1180,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) {
@@ -1218,12 +1250,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(
@@ -1418,7 +1451,19 @@ class CMIValueAccessService {
     if (!scorm2004) {
       if (isFinalAttribute) {
         if (typeof attribute === "undefined" || !this.context.checkObjectHasProperty(refObject, attribute)) {
-          this.context.throwSCORMError(CMIElement, invalidErrorCode, invalidErrorMessage);
+          if (attribute === "_children") {
+            this.context.throwSCORMError(
+              CMIElement,
+              getErrorCode(this.context.errorCodes, "CHILDREN_ERROR")
+            );
+          } else if (attribute === "_count") {
+            this.context.throwSCORMError(
+              CMIElement,
+              getErrorCode(this.context.errorCodes, "COUNT_ERROR")
+            );
+          } else {
+            this.context.throwSCORMError(CMIElement, invalidErrorCode, invalidErrorMessage);
+          }
           return { error: true };
         }
       }
@@ -1923,8 +1968,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;
@@ -1949,9 +1995,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);
         }
@@ -2085,16 +2139,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);
@@ -2173,7 +2230,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",
@@ -2220,17 +2280,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,
@@ -2243,7 +2311,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")) {
@@ -2640,6 +2708,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
@@ -2649,21 +2719,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,
@@ -2678,11 +2750,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);
@@ -2761,9 +2835,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));
   }
   /**
@@ -2837,6 +2917,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.
@@ -3022,6 +3117,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) {
@@ -3106,6 +3202,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
@@ -3126,7 +3268,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(
@@ -3178,6 +3320,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);
@@ -3187,6 +3332,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;
   }
   /**
@@ -3239,9 +3388,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()) {
@@ -3253,8 +3403,9 @@ class BaseAPI {
       this.throwSCORMError("api", errorCode);
       if (errorCode === 143) returnValue = global_constants.SCORM_FALSE;
     } else {
-      const result = this.storeData(false);
-      if ((result.errorCode ?? 0) > 0) {
+      const result = this.storeData(false, trigger);
+      const errorCode = result.errorCode ?? 0;
+      if (errorCode > 0) {
         if (result.errorMessage) {
           this.apiLog(
             "commit",
@@ -3269,12 +3420,12 @@ class BaseAPI {
             LogLevelEnum.DEBUG
           );
         }
-        this.throwSCORMError("api", result.errorCode);
+        this.throwSCORMError("api", errorCode);
       }
       const resultValue = result?.result ?? global_constants.SCORM_FALSE;
       returnValue = typeof resultValue === "boolean" ? String(resultValue) : resultValue;
       this.apiLog(callbackName, " Result: " + returnValue, LogLevelEnum.DEBUG, "HttpRequest");
-      if (checkTerminated) this.lastErrorCode = "0";
+      if (checkTerminated && errorCode === 0) this.lastErrorCode = "0";
       this.processListeners(callbackName);
       if (this.settings.enableOfflineSupport && this._offlineStorageService && this._offlineStorageService.isDeviceOnline() && this._courseId) {
         this._offlineStorageService.hasPendingOfflineData(this._courseId).then((hasPendingData) => {
@@ -3483,7 +3634,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.
@@ -3497,6 +3657,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
    *
@@ -3579,9 +3751,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.
@@ -3714,36 +3891,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.
@@ -3903,6 +4150,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;
@@ -3937,6 +4189,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
@@ -3983,7 +4236,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;
     }
@@ -4007,7 +4261,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;
     }
@@ -4031,7 +4286,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;
     }
@@ -4088,7 +4344,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;
@@ -4518,7 +4776,9 @@ 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;
@@ -5988,16 +6248,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") {
@@ -6026,12 +6287,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,