scorm-again 3.0.4 → 3.1.0

package/dist/scorm12.js

@@ -161,6 +161,15 @@ this.Scorm12API = (function () {
     };
   }
 
+  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}`;
+  };
+
   var __defProp$m = Object.defineProperty;
   var __defNormalProp$m = (obj, key, value) => key in obj ? __defProp$m(obj, key, {
     enumerable: true,
@@ -417,7 +426,10 @@ this.Scorm12API = (function () {
     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
   };
 
@@ -541,6 +553,7 @@ this.Scorm12API = (function () {
     xhrWithCredentials: false,
     fetchMode: "cors",
     asyncModeBeaconBehavior: "never",
+    includeCommitSequence: false,
     responseHandler: async function (response) {
       if (typeof response !== "undefined") {
         let httpResult = null;
@@ -940,7 +953,7 @@ this.Scorm12API = (function () {
     wrapper() {
       if (!this._cancelled) {
         if (this._API.isInitialized()) {
-          (async () => await this._API.commit(this._callback))();
+          (async () => await this._API.commit(this._callback, false, "autocommit"))();
         }
       }
     }
@@ -1430,6 +1443,7 @@ this.Scorm12API = (function () {
      * @param {ErrorCode} error_codes - The error codes object
      */
     constructor(settings, error_codes) {
+      __publicField$h(this, "reportsRequestCompletion", true);
       __publicField$h(this, "settings");
       __publicField$h(this, "error_codes");
       this.settings = settings;
@@ -1448,13 +1462,17 @@ this.Scorm12API = (function () {
      * @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) {
       let immediate = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
       let apiLog = arguments.length > 3 ? arguments[3] : undefined;
       let processListeners = arguments.length > 4 ? arguments[4] : undefined;
-      this._performAsyncRequest(url, params, immediate, apiLog, processListeners);
+      let metadata = arguments.length > 5 ? arguments[5] : undefined;
+      let onRequestComplete = arguments.length > 6 ? arguments[6] : undefined;
+      this._performAsyncRequest(url, params, immediate, apiLog, processListeners, metadata, onRequestComplete);
       return {
         result: global_constants.SCORM_TRUE,
         errorCode: 0
@@ -1467,11 +1485,14 @@ this.Scorm12API = (function () {
      * @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);
@@ -1487,7 +1508,9 @@ this.Scorm12API = (function () {
       } 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?.();
       }
     }
     /**
@@ -1649,10 +1672,13 @@ this.Scorm12API = (function () {
     }
     /**
      * 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
@@ -1676,7 +1702,7 @@ this.Scorm12API = (function () {
       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) {
@@ -1716,12 +1742,13 @@ this.Scorm12API = (function () {
         this.context.throwSCORMError(CMIElement, getErrorCode(this.context.errorCodes, "GENERAL_GET_FAILURE"), "The _version keyword was used incorrectly");
         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(refObject, attribute, CMIElement, scorm2004, invalidErrorCode, invalidErrorMessage, idx === structure.length - 1);
@@ -1906,7 +1933,13 @@ this.Scorm12API = (function () {
       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
             };
@@ -2441,8 +2474,9 @@ ${stackTrace}`);
      * @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;
@@ -2462,9 +2496,17 @@ ${stackTrace}`);
           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);
           }
@@ -2573,16 +2615,23 @@ ${stackTrace}`);
      * 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);
@@ -2641,7 +2690,14 @@ ${stackTrace}`);
             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", `Successfully synced item ${item.id}`, LogLevelEnum.INFO);
             } else {
@@ -2668,17 +2724,27 @@ ${stackTrace}`);
     /**
      * 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,
@@ -2691,7 +2757,7 @@ ${stackTrace}`);
         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")) {
@@ -3422,6 +3488,8 @@ ${stackTrace}`);
      * @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
@@ -3433,20 +3501,23 @@ ${stackTrace}`);
      */
     processHttpRequest(url, params) {
       let immediate = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
+      let metadata = arguments.length > 5 ? arguments[5] : undefined;
       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);
@@ -3462,11 +3533,13 @@ ${stackTrace}`);
      * 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
@@ -3539,9 +3612,16 @@ ${stackTrace}`);
      * @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) {
+      let allowEmptyString = arguments.length > 7 && arguments[7] !== undefined ? arguments[7] : false;
+      if (allowEmptyString && value === "") {
+        return true;
+      }
       return checkValidFormat(CMIElement, value, decimalRegex, invalidTypeCode, errorClass) && (!scoreRange || checkValidRange(CMIElement, value, scoreRange, invalidRangeCode, errorClass));
     }
     /**
@@ -3637,6 +3717,21 @@ ${stackTrace}`);
       __publicField$9(this, "_offlineStorageService");
       __publicField$9(this, "_cmiValueAccessService");
       __publicField$9(this, "_courseId", "");
+      __publicField$9(this, "_pendingCommitCount", 0);
+      /**
+       * Monotonic sequence for commits captured by this API instance. It is
+       * intentionally not reset by reset().
+       */
+      __publicField$9(this, "_commitSequence", 0);
+      __publicField$9(this, "_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".
+       */
+      __publicField$9(this, "_setCMIElements", /* @__PURE__ */new Set());
       __publicField$9(this, "startingData");
       __publicField$9(this, "currentState");
       if (new.target === BaseAPI) {
@@ -3783,6 +3878,7 @@ ${stackTrace}`);
       this.lastErrorCode = "0";
       this._eventService.reset();
       this.startingData = {};
+      this._setCMIElements.clear();
       if (this._offlineStorageService) {
         this._offlineStorageService.updateSettings(this.settings);
         if (settings?.courseId) {
@@ -3866,6 +3962,54 @@ ${stackTrace}`);
         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
@@ -3886,7 +4030,7 @@ ${stackTrace}`);
       } 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("terminate", `Terminate failed with error: ${result.errorMessage}`, LogLevelEnum.ERROR);
@@ -3926,6 +4070,9 @@ ${stackTrace}`);
         } 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);
@@ -3935,6 +4082,10 @@ ${stackTrace}`);
       if (this.lastErrorCode === "0") {
         this.clearSCORMError(returnValue);
       }
+      const rawReturn = returnValue;
+      if (typeof rawReturn === "number" || typeof rawReturn === "boolean") {
+        return String(rawReturn);
+      }
       return returnValue;
     }
     /**
@@ -3978,10 +4129,12 @@ ${stackTrace}`);
      * Orders LMS to store all content parameters
      * @param {string} callbackName
      * @param {boolean} checkTerminated
+     * @param {CommitTrigger} trigger - What initiated the commit
      * @return {string}
      */
     commit(callbackName) {
       let checkTerminated = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+      let trigger = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : "manual";
       this.clearScheduledCommit();
       let returnValue = global_constants.SCORM_TRUE;
       if (this.isNotInitialized()) {
@@ -3993,20 +4146,21 @@ ${stackTrace}`);
         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", `Commit failed with error: ${result.errorMessage}`, LogLevelEnum.ERROR);
           }
           if (result.errorDetails) {
             this.apiLog("commit", `Error details: ${JSON.stringify(result.errorDetails)}`, 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 => {
@@ -4213,7 +4367,11 @@ ${stackTrace}`);
      * @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.
@@ -4227,6 +4385,17 @@ ${stackTrace}`);
     _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
      *
@@ -4309,9 +4478,14 @@ ${stackTrace}`);
      * @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.
@@ -4433,23 +4607,97 @@ ${stackTrace}`);
      * @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) {
       let immediate = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 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 {
-          this.apiLog("processHttpRequest", "Invalid commit data format for offline storage", LogLevelEnum.ERROR);
-          return {
-            result: global_constants.SCORM_FALSE,
-            errorCode: this._error_codes.GENERAL ?? 101
-          };
+      let trigger = arguments.length > 3 ? arguments[3] : undefined;
+      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", "Device is offline, storing data locally", LogLevelEnum.INFO);
+          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.
@@ -4633,6 +4881,11 @@ ${stackTrace}`);
       __publicField$8(this, "__invalid_range_code");
       __publicField$8(this, "__decimal_regex");
       __publicField$8(this, "__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.
+       */
+      __publicField$8(this, "__allow_empty_string");
       __publicField$8(this, "_raw", "");
       __publicField$8(this, "_min", "");
       __publicField$8(this, "_max");
@@ -4644,6 +4897,7 @@ ${stackTrace}`);
       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
@@ -4683,7 +4937,7 @@ ${stackTrace}`);
      * @param {string} raw
      */
     set raw(raw) {
-      if (validationService.validateScore(this._cmi_element + ".raw", raw, this.__decimal_regex, this.__score_range, this.__invalid_type_code, this.__invalid_range_code, this.__error_class)) {
+      if (validationService.validateScore(this._cmi_element + ".raw", raw, this.__decimal_regex, this.__score_range, this.__invalid_type_code, this.__invalid_range_code, this.__error_class, this.__allow_empty_string)) {
         this._raw = raw;
       }
     }
@@ -4699,7 +4953,7 @@ ${stackTrace}`);
      * @param {string} min
      */
     set min(min) {
-      if (validationService.validateScore(this._cmi_element + ".min", min, this.__decimal_regex, this.__score_range, this.__invalid_type_code, this.__invalid_range_code, this.__error_class)) {
+      if (validationService.validateScore(this._cmi_element + ".min", min, this.__decimal_regex, this.__score_range, this.__invalid_type_code, this.__invalid_range_code, this.__error_class, this.__allow_empty_string)) {
         this._min = min;
       }
     }
@@ -4715,7 +4969,7 @@ ${stackTrace}`);
      * @param {string} max
      */
     set max(max) {
-      if (validationService.validateScore(this._cmi_element + ".max", max, this.__decimal_regex, this.__score_range, this.__invalid_type_code, this.__invalid_range_code, this.__error_class)) {
+      if (validationService.validateScore(this._cmi_element + ".max", max, this.__decimal_regex, this.__score_range, this.__invalid_type_code, this.__invalid_range_code, this.__error_class, this.__allow_empty_string)) {
         this._max = max;
       }
     }
@@ -4792,7 +5046,9 @@ ${stackTrace}`);
         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
       });
     }
     /**
@@ -5160,7 +5416,9 @@ ${stackTrace}`);
         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
       });
     }
     /**
@@ -6597,16 +6855,17 @@ ${stackTrace}`);
      * 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") {
@@ -6635,12 +6894,12 @@ ${stackTrace}`);
           }
         }
       }
-      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,