coursecode 0.1.57 → 0.1.58

package/framework/js/state/state-manager.js

@@ -50,6 +50,7 @@ class StateManager {
     constructor() {
         this.isInitialized = false;
         this.isTerminated = false;
+        this._terminationPromise = null;
 
         // Compose internal modules
         this._txLog = new TransactionLog();
@@ -148,6 +149,12 @@ class StateManager {
         }
         this._assertInitialized();
 
+        // Validate semantic domains before mutating suspend-data state. This
+        // prevents a failed LMS write from first persisting invalid CMI data.
+        if (domain === 'objectives' && value) {
+            this._assertValidObjectives(value);
+        }
+
         const result = this._domains.setDomainState(domain, value, meta);
 
         // Report to driver for format-specific handling
@@ -171,7 +178,28 @@ class StateManager {
         this._assertInitialized();
         this._assertNotTerminated('Cannot clear data after termination.');
 
-        logger.debug('[StateManager] Clearing all suspend data for course restart');
+        logger.debug('[StateManager] Resetting learner progress for course restart');
+
+        // Native CMI arrays are append-only and cannot be deleted, but their
+        // objective status can be returned to a neutral state. Historical
+        // interaction rows remain as an LMS audit trail and no longer affect
+        // the freshly cleared CourseCode state.
+        const objectives = this._domains.getDomainState('objectives') || {};
+        for (const id of Object.keys(objectives)) {
+            lmsConnection.reportObjective({
+                id,
+                completion_status: 'incomplete',
+                success_status: 'unknown',
+                score: 0,
+                progress_measure: 0
+            });
+        }
+
+        lmsConnection.setBookmark('');
+        lmsConnection.reportCompletion('incomplete');
+        lmsConnection.reportSuccess('unknown');
+        lmsConnection.reportScore({ raw: 0, scaled: 0, min: 0, max: 100 });
+        lmsConnection.reportProgress(0);
         this._domains.clearState();
         await this._commits.commitToLMS();
         eventBus.emit('state:cleared', { reason: 'course restart' });
@@ -212,24 +240,28 @@ class StateManager {
             throw new Error('StateManager: bookmark exceeds maximum length (1024)');
         }
         lmsConnection.setBookmark(slideId);
+        this._commits.scheduleCommit(false);
     }
 
     /** @param {{raw: number, scaled: number, min: number, max: number}} score */
     reportScore(score) {
         this._assertValidScore(score);
         lmsConnection.reportScore(score);
+        this._commits.scheduleCommit(false);
     }
 
     /** @param {string} status - 'completed' | 'incomplete' */
     reportCompletion(status) {
         this._assertValidCompletionStatus(status);
         lmsConnection.reportCompletion(status);
+        this._commits.scheduleCommit(false);
     }
 
     /** @param {string} status - 'passed' | 'failed' | 'unknown' */
     reportSuccess(status) {
         this._assertValidSuccessStatus(status);
         lmsConnection.reportSuccess(status);
+        this._commits.scheduleCommit(false);
     }
 
     /** @returns {string} Current completion status */
@@ -302,22 +334,52 @@ class StateManager {
         return await this.terminate();
     }
 
+    /**
+     * Synchronously stages the newest in-memory state for an unload handler.
+     * No Promise is used because browsers do not wait for asynchronous work
+     * during pagehide.
+     */
+    prepareEmergencySave() {
+        if (!this.isInitialized || this.isTerminated) return;
+        this._reportSessionTime();
+        lmsConnection.setExitMode('suspend');
+        lmsConnection.setSuspendData(this._domains.state);
+    }
+
     /**
      * Terminates the LMS connection with a final commit.
      */
     async terminate() {
         this._assertInitialized();
+
+        // Coalesce concurrent exit requests so the final commit and LMS
+        // termination happen exactly once.
+        if (this._terminationPromise) {
+            return await this._terminationPromise;
+        }
+
         this._assertNotTerminated('Cannot terminate again.');
 
         logger.debug('[StateManager] Terminating...');
 
-        // Emit BEFORE termination so services can send final xAPI statements
-        await eventBus.emitAsync('session:beforeTerminate');
+        this._terminationPromise = (async () => {
+            // Emit BEFORE termination so services can send final xAPI statements
+            await eventBus.emitAsync('session:beforeTerminate');
 
-        await this._commits.commitToLMS();
-        this.isTerminated = true;
+            await this._commits.commitToLMS();
+            const result = await lmsConnection.terminate();
 
-        return await lmsConnection.terminate();
+            // Do not strand the manager in a terminated state when the LMS
+            // operation rejects; callers must be able to retry.
+            this.isTerminated = true;
+            return result;
+        })();
+
+        try {
+            return await this._terminationPromise;
+        } finally {
+            this._terminationPromise = null;
+        }
     }
 
     // =================================================================
@@ -327,8 +389,9 @@ class StateManager {
     /**
      * Updates progress_measure based on visited slides.
      * @param {number} totalSlides - Total sequential slides
+     * @param {string[]|null} eligibleSlideIds - Active-sequence slide IDs
      */
-    updateProgressMeasure(totalSlides) {
+    updateProgressMeasure(totalSlides, eligibleSlideIds = null) {
         this._assertInitialized();
         this._assertNotTerminated('Cannot update progress after termination.');
         if (!totalSlides || totalSlides <= 0) {
@@ -338,13 +401,18 @@ class StateManager {
         try {
             const navigationState = this.getDomainState('navigation') || {};
             const visitedSlides = navigationState.visitedSlides || [];
-            const visitedCount = visitedSlides.length;
+            const eligible = Array.isArray(eligibleSlideIds) ? new Set(eligibleSlideIds) : null;
+            const eligibleVisitedSlides = eligible
+                ? visitedSlides.filter(slideId => eligible.has(slideId))
+                : visitedSlides;
+            const visitedCount = eligibleVisitedSlides.length;
 
             let progressMeasure = Math.min(visitedCount / totalSlides, 1.0);
             progressMeasure = Math.max(0, Math.min(1, progressMeasure));
             progressMeasure = Math.round(progressMeasure * 100) / 100;
 
             lmsConnection.reportProgress(progressMeasure);
+            this._commits.scheduleCommit(false);
 
             logger.debug(`[StateManager] Progress measure updated: ${progressMeasure} (${(progressMeasure * 100).toFixed(0)}%)`);
             logger.debug(`  - Slides visited: ${visitedCount}/${totalSlides}`);
@@ -420,11 +488,19 @@ class StateManager {
     _reportObjectivesToDriver(objectives) {
         if (!objectives || typeof objectives !== 'object') return;
         for (const [id, objective] of Object.entries(objectives)) {
-            this._assertValidObjective({ id, ...objective });
             lmsConnection.reportObjective({ id, ...objective });
         }
     }
 
+    _assertValidObjectives(objectives) {
+        if (!objectives || typeof objectives !== 'object' || Array.isArray(objectives)) {
+            throw new Error('StateManager: objectives must be an object keyed by objective ID');
+        }
+        for (const [id, objective] of Object.entries(objectives)) {
+            this._assertValidObjective({ id, ...objective });
+        }
+    }
+
     _reportSessionTime() {
         try {
             const sessionStartTime = lmsConnection.sessionStart;
@@ -492,6 +568,16 @@ class StateManager {
                 throw new Error(`StateManager: objective.progress_measure must be between 0 and 1, got ${objective.progress_measure}`);
             }
         }
+
+
+        if (objective.completion_status !== undefined &&
+            !VALID_COMPLETION_STATUSES.has(objective.completion_status)) {
+            throw new Error(`StateManager: invalid objective completion status "${objective.completion_status}"`);
+        }
+        if (objective.success_status !== undefined &&
+            !VALID_SUCCESS_STATUSES.has(objective.success_status)) {
+            throw new Error(`StateManager: invalid objective success status "${objective.success_status}"`);
+        }
     }
 }
 

package/framework/js/state/state-validation.js

@@ -107,6 +107,7 @@ export class StateValidator {
         return {
             _meta: {
                 schemaVersion: STATE_SCHEMA_VERSION,
+                courseVersion: this._validationConfig?.courseVersion || null,
                 createdAt: new Date().toISOString()
             }
         };
@@ -162,8 +163,9 @@ export class StateValidator {
             return loadedState;
         }
 
-        const { slideIds, objectiveIds: _objectiveIds } = this._validationConfig;
+        const { slideIds, objectiveIds: _objectiveIds, courseVersion } = this._validationConfig;
         const storedSchemaVersion = loadedState._meta?.schemaVersion || 0;
+        const storedCourseVersion = loadedState._meta?.courseVersion || null;
 
         logger.debug(`[StateManager] Validating state: stored schema v${storedSchemaVersion}, current v${STATE_SCHEMA_VERSION}`);
 
@@ -182,34 +184,65 @@ export class StateValidator {
             loadedState = this._runMigrations(loadedState, storedSchemaVersion, STATE_SCHEMA_VERSION);
         }
 
-        const validatedState = { ...loadedState };
+        let validatedState = { ...loadedState };
+
+        if (storedCourseVersion && courseVersion && storedCourseVersion !== courseVersion) {
+            validatedState = this._invalidateVersionSensitiveState(validatedState);
+            logger.warn(
+                `[StateManager] Course version changed from ${storedCourseVersion} to ${courseVersion}; ` +
+                'cleared in-progress assessment responses and authored interaction responses while preserving earned summaries.'
+            );
+            eventBus.emit('state:recovered', {
+                domain: '_meta',
+                message: `Course version changed from ${storedCourseVersion} to ${courseVersion}`,
+                context: { storedCourseVersion, courseVersion },
+                action: 'invalidated_version_sensitive_state'
+            });
+        }
 
         validatedState._meta = {
-            ...loadedState._meta,
+            ...validatedState._meta,
             schemaVersion: STATE_SCHEMA_VERSION,
+            courseVersion,
             lastValidatedAt: new Date().toISOString()
         };
 
-        if (loadedState.navigation) {
-            validatedState.navigation = this._validateNavigationState(loadedState.navigation, slideIds);
+        if (validatedState.navigation) {
+            validatedState.navigation = this._validateNavigationState(validatedState.navigation, slideIds);
         }
-        if (loadedState.engagement) {
-            validatedState.engagement = this._validateEngagementState(loadedState.engagement, slideIds);
+        if (validatedState.engagement) {
+            validatedState.engagement = this._validateEngagementState(validatedState.engagement, slideIds);
         }
-        if (loadedState.interactionResponses) {
-            validatedState.interactionResponses = this._validateInteractionResponsesState(loadedState.interactionResponses);
+        if (validatedState.interactionResponses) {
+            validatedState.interactionResponses = this._validateInteractionResponsesState(validatedState.interactionResponses);
         }
 
-        for (const key of Object.keys(loadedState)) {
+        for (const key of Object.keys(validatedState)) {
             if (key.startsWith('assessment_')) {
                 const assessmentId = key.replace('assessment_', '');
-                validatedState[key] = this._validateAssessmentState(loadedState[key], assessmentId);
+                validatedState[key] = this._validateAssessmentState(validatedState[key], assessmentId);
             }
         }
 
         return validatedState;
     }
 
+    _invalidateVersionSensitiveState(state) {
+        const recovered = { ...state };
+        delete recovered.interactionResponses;
+
+        for (const key of Object.keys(recovered)) {
+            if (!key.startsWith('assessment_')) continue;
+            const assessment = recovered[key];
+            if (!assessment || typeof assessment !== 'object' || !assessment.session) continue;
+
+            recovered[key] = { ...assessment };
+            delete recovered[key].session;
+        }
+
+        return recovered;
+    }
+
     _runMigrations(state, fromVersion, toVersion) {
         let migratedState = { ...state };
 

package/framework/js/utilities/course-helpers.js

@@ -204,6 +204,9 @@ async function computeDerived() {
             if (!slideId) {
                 throw new Error('Slide is missing an id');
             }
+            if (Object.prototype.hasOwnProperty.call(indexById, slideId)) {
+                throw new Error(`[CourseHelpers] Duplicate slide ID '${slideId}' found. Each slide must have a unique ID.`);
+            }
 
             let component;
             let assessmentId = null;
@@ -416,5 +419,3 @@ function normalizeComponentPath(path) {
 
     return normalized;
 }
-
-

package/framework/js/utilities/media-utils.js

@@ -0,0 +1,28 @@
+/** Default fraction of media that must be consumed for completion. */
+export const DEFAULT_MEDIA_COMPLETION_THRESHOLD = 0.95;
+
+/**
+ * Normalizes authored media completion thresholds from JS config or data
+ * attributes. Values outside the documented 0-1 range fall back to the
+ * framework default instead of creating media that can never complete.
+ * @param {number|string|null|undefined} value
+ * @returns {number}
+ */
+export function normalizeCompletionThreshold(value) {
+    if (value === null || value === undefined) {
+        return DEFAULT_MEDIA_COMPLETION_THRESHOLD;
+    }
+
+    if (typeof value !== 'number' && typeof value !== 'string') {
+        return DEFAULT_MEDIA_COMPLETION_THRESHOLD;
+    }
+
+    if (typeof value === 'string' && value.trim() === '') {
+        return DEFAULT_MEDIA_COMPLETION_THRESHOLD;
+    }
+
+    const parsed = typeof value === 'number' ? value : Number(value.trim());
+    return Number.isFinite(parsed) && parsed >= 0 && parsed <= 1
+        ? parsed
+        : DEFAULT_MEDIA_COMPLETION_THRESHOLD;
+}

package/framework/js/utilities/portable-assets.js

@@ -0,0 +1,131 @@
+/**
+ * Runtime helpers for CourseCode portable HTML exports.
+ *
+ * Normal LMS and hosted builds do not define the global asset map, so every
+ * helper is a cheap no-op outside a portable build.
+ */
+
+const URL_ATTRIBUTES = [
+    'src',
+    'href',
+    'poster',
+    'data-src',
+    'data-audio-src',
+    'data-video-src',
+    'data-video-poster',
+    'data-video-captions',
+    'data-lightbox-src',
+    'data-lightbox-thumbnail',
+    'data-md-src'
+];
+
+function getAssetMap() {
+    if (typeof window === 'undefined') return null;
+    const map = window.__COURSECODE_PORTABLE_ASSETS__;
+    return map && typeof map === 'object' ? map : null;
+}
+
+function stripQueryAndHash(value) {
+    return value.split('#', 1)[0].split('?', 1)[0];
+}
+
+function candidateKeys(value) {
+    const clean = stripQueryAndHash(value)
+        .replace(/\\/g, '/')
+        .replace(/^(?:\.\/)+/, '')
+        .replace(/^\//, '');
+    const keys = new Set([clean]);
+
+    if (clean.startsWith('course/')) keys.add(clean.slice('course/'.length));
+    if (clean.startsWith('course/assets/')) {
+        const relative = clean.slice('course/assets/'.length);
+        keys.add(`assets/${relative}`);
+        keys.add(relative);
+    } else if (clean.startsWith('assets/')) {
+        const relative = clean.slice('assets/'.length);
+        keys.add(`course/assets/${relative}`);
+        keys.add(relative);
+    } else if (clean && !clean.startsWith('_')) {
+        keys.add(`course/assets/${clean}`);
+        keys.add(`assets/${clean}`);
+    }
+
+    return keys;
+}
+
+/**
+ * Resolve a course-relative URL to its embedded data URL when running from a
+ * portable HTML export.
+ * @param {string} value
+ * @returns {string}
+ */
+export function resolvePortableAssetUrl(value) {
+    if (typeof value !== 'string' || value.length === 0) return value;
+    if (/^(?:data:|blob:|https?:|mailto:|tel:|#|\/\/)/i.test(value)) return value;
+
+    const map = getAssetMap();
+    if (!map) return value;
+
+    for (const key of candidateKeys(value)) {
+        if (typeof map[key] === 'string') return map[key];
+    }
+    return value;
+}
+
+/**
+ * Rewrite URL-bearing attributes in freshly rendered slide DOM before
+ * declarative components initialize and begin loading media.
+ * @param {HTMLElement} root
+ */
+export function rewritePortableAssetAttributes(root) {
+    if (!root || !getAssetMap()) return;
+
+    const elements = [root, ...root.querySelectorAll('*')];
+    for (const element of elements) {
+        for (const attribute of URL_ATTRIBUTES) {
+            if (!element.hasAttribute?.(attribute)) continue;
+            const current = element.getAttribute(attribute);
+            const resolved = resolvePortableAssetUrl(current);
+            if (resolved !== current) element.setAttribute(attribute, resolved);
+        }
+
+        const style = element.getAttribute?.('style');
+        if (!style || !style.includes('url(')) continue;
+        const rewritten = style.replace(/url\((['"]?)([^)'"\s]+)\1\)/g, (match, quote, url) => {
+            const resolved = resolvePortableAssetUrl(url);
+            return resolved === url ? match : `url(${quote}${resolved}${quote})`;
+        });
+        if (rewritten !== style) element.setAttribute('style', rewritten);
+    }
+}
+
+/**
+ * Replace asset-looking strings inside course configuration objects. This
+ * covers branding, narration, and programmatic component configuration that
+ * never appears as DOM until after managers initialize.
+ * @param {unknown} value
+ * @param {WeakSet<object>} [seen]
+ * @returns {unknown}
+ */
+export function hydratePortableAssetObject(value, seen = new WeakSet()) {
+    if (!getAssetMap()) return value;
+    if (typeof value === 'string') return resolvePortableAssetUrl(value);
+    if (!value || typeof value !== 'object' || seen.has(value)) return value;
+
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++) {
+            value[index] = hydratePortableAssetObject(value[index], seen);
+        }
+        return value;
+    }
+
+    for (const [key, child] of Object.entries(value)) {
+        value[key] = hydratePortableAssetObject(child, seen);
+    }
+    return value;
+}
+
+export function isPortableHtml() {
+    return Boolean(getAssetMap());
+}

package/framework/js/utilities/ui-initializer.js

@@ -6,7 +6,7 @@
 
 import { logger } from './logger.js';
 import { getComponentInit, getComponentStyles, isComponentRegistered, getRegisteredComponentTypes } from '../core/component-catalog.js';
-import { init as initNotificationTriggers } from '../components/ui-components/notifications.js';
+import { initNotificationTriggers } from '../components/ui-components/notifications.js';
 
 
 import engagementManager from '../engagement/engagement-manager.js';
@@ -15,6 +15,11 @@ import * as NavigationState from '../navigation/NavigationState.js';
 // Track which custom component styles have been injected
 const injectedStyles = new Set();
 
+// Component initializers may return an object with destroy(), or a cleanup
+// function directly. Keep those handles with the rendered view so ViewManager
+// can release document-level listeners and other resources before removing it.
+const componentCleanups = new WeakMap();
+
 /**
  * Inject custom component styles into the document head
  * @param {string} type - Component type
@@ -39,7 +44,14 @@ export function initializeDeclarativeComponents(container) {
         return;
     }
 
-    const components = container.querySelectorAll('[data-component]');
+    // Re-initializing the same rendered view should not stack event listeners.
+    cleanupDeclarativeComponents(container);
+
+    const components = [
+        ...(container.matches?.('[data-component]') ? [container] : []),
+        ...container.querySelectorAll('[data-component]')
+    ];
+    const cleanups = [];
 
     components.forEach(element => {
         const componentName = element.dataset.component;
@@ -59,7 +71,12 @@ export function initializeDeclarativeComponents(container) {
         const initializer = getComponentInit(componentName);
         if (initializer && typeof initializer === 'function') {
             try {
-                initializer(element);
+                const instance = initializer(element);
+                if (typeof instance === 'function') {
+                    cleanups.push(instance);
+                } else if (instance && typeof instance.destroy === 'function') {
+                    cleanups.push(() => instance.destroy());
+                }
             } catch (error) {
                 logger.error(`[UI-Initializer] Failed to initialize '${componentName}' component: ${error.message}`, { domain: 'ui', operation: 'initializeComponent', stack: error.stack, component: componentName });
             }
@@ -77,13 +94,48 @@ export function initializeDeclarativeComponents(container) {
     // This must happen AFTER all modal triggers are initialized
     registerModalsForEngagement(container);
 
+    // Register hotspots across every interactive image in the rendered view as
+    // one batch so revisiting a slide cannot inflate engagement totals.
+    registerInteractiveImagesForEngagement(container);
+
     // Initialize declarative notification triggers (event delegation pattern)
-    initNotificationTriggers(container);
+    const notificationInstance = initNotificationTriggers(container);
+    if (notificationInstance && typeof notificationInstance.destroy === 'function') {
+        cleanups.push(() => notificationInstance.destroy());
+    }
 
 
     // Register lightbox triggers with engagement manager (batch registration)
     // This must happen AFTER all lightbox triggers are initialized by the catalog
     registerLightboxesForEngagement(container);
+
+    if (cleanups.length > 0) {
+        componentCleanups.set(container, cleanups);
+    }
+}
+
+/**
+ * Destroys declarative component instances associated with a rendered view.
+ * Cleanup is best-effort so one faulty component cannot prevent the rest from
+ * releasing their resources.
+ * @param {HTMLElement} container - The rendered view that was initialized.
+ */
+export function cleanupDeclarativeComponents(container) {
+    const cleanups = componentCleanups.get(container);
+    if (!cleanups) return;
+
+    componentCleanups.delete(container);
+    for (const cleanup of [...cleanups].reverse()) {
+        try {
+            cleanup();
+        } catch (error) {
+            logger.error(`[UI-Initializer] Component cleanup failed: ${error.message}`, {
+                domain: 'ui',
+                operation: 'cleanupComponent',
+                stack: error.stack
+            });
+        }
+    }
 }
 
 /**
@@ -124,6 +176,28 @@ function registerModalsForEngagement(container) {
     }
 }
 
+/**
+ * Registers every interactive-image hotspot in the rendered view as one batch.
+ * @param {HTMLElement} container - The container to scan for hotspots
+ */
+function registerInteractiveImagesForEngagement(container) {
+    const hotspots = container.querySelectorAll(
+        '[data-component="interactive-image"] [data-hotspot-id]'
+    );
+    if (!hotspots.length) return;
+
+    const currentSlideId = NavigationState.getCurrentSlideId();
+    if (!currentSlideId) return;
+
+    const hotspotIds = Array.from(hotspots)
+        .map(hotspot => hotspot.dataset.hotspotId)
+        .filter(Boolean);
+    if (hotspotIds.length > 0) {
+        engagementManager.registerInteractiveImages(currentSlideId, hotspotIds);
+        logger.debug(`[UI-Initializer] Registered ${hotspotIds.length} interactive-image hotspots for engagement tracking`);
+    }
+}
+
 /**
  * Registers all lightbox triggers in the container with the engagement manager.
  * This batch registration ensures lightboxesTotal is set correctly after all triggers are found.
@@ -140,7 +214,7 @@ function registerLightboxesForEngagement(container) {
         .map(trigger => trigger.id || trigger.dataset.lightboxId)
         .filter(Boolean);
     if (lightboxIds.length > 0) {
-        engagementManager.registerLightbox(currentSlideId, lightboxIds);
+        engagementManager.registerLightboxes(currentSlideId, lightboxIds);
         logger.debug(`[UI-Initializer] Registered ${lightboxIds.length} lightboxes for engagement tracking`);
     }
 }