coursecode 0.1.56 → 0.1.58

package/framework/js/drivers/standalone-driver.js

@@ -0,0 +1,139 @@
+/**
+ * @file standalone-driver.js
+ * @description Local persistence driver for portable, single-file HTML courses.
+ */
+
+import { HttpDriverBase } from './http-driver-base.js';
+import { logger } from '../utilities/logger.js';
+
+function slug(value) {
+    return String(value || 'course')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 80) || 'course';
+}
+
+export class StandaloneDriver extends HttpDriverBase {
+    constructor() {
+        super();
+        const courseId = typeof document !== 'undefined'
+            ? (document.querySelector('meta[name="coursecode-id"]')?.content || document.title)
+            : 'course';
+        this._storageKey = `coursecode-portable:${slug(courseId)}`;
+        this._storageAvailable = true;
+    }
+
+    getFormat() {
+        return 'standalone';
+    }
+
+    getCapabilities() {
+        return {
+            supportsObjectives: true,
+            supportsInteractions: true,
+            supportsComments: true,
+            supportsEmergencySave: true,
+            maxSuspendDataBytes: 0,
+            asyncCommit: false
+        };
+    }
+
+    async initialize() {
+        if (this._isConnected) return true;
+        this._mock = true;
+        this._loadMockState();
+        this._isConnected = true;
+        this._isTerminated = false;
+        logger.debug('[StandaloneDriver] Portable course initialized', {
+            restoreAvailable: this._storageAvailable,
+            resumed: Boolean(this._bookmarkCache)
+        });
+        return true;
+    }
+
+    async terminate() {
+        if (!this._isConnected || this._isTerminated) return true;
+        this._saveMockState();
+        this._isTerminated = true;
+        return true;
+    }
+
+    emergencySave() {
+        this._saveMockState();
+    }
+
+    getLearnerInfo() {
+        return { id: 'local-learner', name: 'Learner' };
+    }
+
+    getLaunchData() {
+        return null;
+    }
+
+    async _persistState() {
+        this._saveMockState();
+    }
+
+    _loadMockState() {
+        let stored;
+        try {
+            stored = localStorage.getItem(this._storageKey);
+        } catch (error) {
+            this._storageAvailable = false;
+            logger.warn('[StandaloneDriver] Browser restore storage is unavailable; progress will last for this session only', {
+                domain: 'standalone',
+                operation: 'loadState',
+                error: error.message
+            });
+            return;
+        }
+
+        if (!stored) return;
+        try {
+            const state = JSON.parse(stored);
+            if (!state || typeof state !== 'object') return;
+
+            this._mockState = state;
+            this._bookmarkCache = state.bookmark || null;
+            this._completionStatus = state.completionStatus || 'unknown';
+            this._successStatus = state.successStatus || 'unknown';
+            this._score = state.score ?? null;
+        } catch (error) {
+            this._mockState = {};
+            logger.warn('[StandaloneDriver] Ignoring invalid saved progress and starting a new local session', {
+                domain: 'standalone',
+                operation: 'parseState',
+                error: error.message
+            });
+            try {
+                localStorage.removeItem(this._storageKey);
+            } catch {
+                this._storageAvailable = false;
+            }
+        }
+    }
+
+    _saveMockState() {
+        const state = {
+            ...this._mockState,
+            bookmark: this._bookmarkCache,
+            completionStatus: this._completionStatus,
+            successStatus: this._successStatus,
+            score: this._score
+        };
+        this._mockState = state;
+
+        if (!this._storageAvailable) return;
+        try {
+            localStorage.setItem(this._storageKey, JSON.stringify(state));
+        } catch (error) {
+            this._storageAvailable = false;
+            logger.warn('[StandaloneDriver] Could not persist portable course progress', {
+                domain: 'standalone',
+                operation: 'saveState',
+                error: error.message
+            });
+        }
+    }
+}

package/framework/js/engagement/engagement-trackers.js

@@ -16,34 +16,49 @@ import { logger } from '../utilities/logger.js';
 /**
  * Creates a batch registration function that sets tracked[totalField] = ids.length.
  */
-function makeRegister(totalField, label) {
+function makeRegister(totalField, label, registeredField = null) {
     // Derive the viewed field name from the total field (e.g., 'tabsTotal' → 'tabsViewed')
     const viewedField = totalField.replace('Total', 'Viewed');
     return function (slideId, ids) {
         if (!slideId || !Array.isArray(ids)) return;
         const state = this._getState();
         if (!state[slideId]) return;
-        state[slideId].tracked[totalField] = ids.length;
-        // Reset viewed array on re-registration to prevent viewed > total inconsistency
-        state[slideId].tracked[viewedField] = [];
+        const tracked = state[slideId].tracked;
+        const registeredIds = [...new Set(ids.filter(Boolean))];
+        const registeredIdSet = new Set(registeredIds);
+
+        tracked[totalField] = registeredIds.length;
+        if (registeredField) {
+            tracked[registeredField] = registeredIds;
+        }
+        // Views render fresh during navigation. Preserve valid persisted progress
+        // while pruning IDs that no longer exist in the authored content.
+        tracked[viewedField] = [...new Set(tracked[viewedField] || [])]
+            .filter(id => registeredIdSet.has(id));
         this._setState(state);
-        logger.debug(`[EngagementManager] Registered ${ids.length} ${label}: ${slideId}`);
+        logger.debug(`[EngagementManager] Registered ${registeredIds.length} ${label}: ${slideId}`);
         this._checkAndEmitProgress(slideId);
     };
 }
 
 /**
- * Creates an incremental registration function that adds to total and inits viewed array.
+ * Creates a deduplicating incremental registration function for components
+ * that can register independently within the same rendered view.
  */
-function makeRegisterIncremental(totalField, viewedField, label) {
+function makeRegisterIncremental(totalField, registeredField, label) {
+    const viewedField = totalField.replace('Total', 'Viewed');
     return function (slideId, ids) {
         if (!slideId || !Array.isArray(ids)) return;
         const state = this._getState();
         if (!state[slideId]) return;
-        state[slideId].tracked[totalField] = (state[slideId].tracked[totalField] || 0) + ids.length;
-        if (!state[slideId].tracked[viewedField]) {
-            state[slideId].tracked[viewedField] = [];
+        const tracked = state[slideId].tracked;
+        if (!Array.isArray(tracked[viewedField])) {
+            tracked[viewedField] = [];
         }
+        const registeredIds = new Set(tracked[registeredField] || []);
+        ids.filter(Boolean).forEach(id => registeredIds.add(id));
+        tracked[registeredField] = [...registeredIds];
+        tracked[totalField] = registeredIds.size;
         this._setState(state);
         logger.debug(`[EngagementManager] Registered ${ids.length} ${label}: ${slideId}`);
         this._checkAndEmitProgress(slideId);
@@ -101,10 +116,16 @@ export const registerTimeline = makeRegister('timelineEventsTotal', 'timeline ev
 export const registerModals = makeRegister('modalsTotal', 'modals');
 
 export const registerInteractiveImage = makeRegisterIncremental(
-    'interactiveImageHotspotsTotal', 'interactiveImageHotspotsViewed', 'hotspots'
+    'interactiveImageHotspotsTotal', 'interactiveImageHotspotsRegistered', 'hotspots'
 );
 export const registerLightbox = makeRegisterIncremental(
-    'lightboxesTotal', 'lightboxesViewed', 'lightboxes'
+    'lightboxesTotal', 'lightboxesRegistered', 'lightboxes'
+);
+export const registerInteractiveImages = makeRegister(
+    'interactiveImageHotspotsTotal', 'hotspots', 'interactiveImageHotspotsRegistered'
+);
+export const registerLightboxes = makeRegister(
+    'lightboxesTotal', 'lightboxes', 'lightboxesRegistered'
 );
 
 // =========================================================================
@@ -153,6 +174,10 @@ export const trackSlideVideoComplete = makeBoolTracker('videoComplete', 'Slide v
 /** Interaction tracking — uses object map keyed by interactionId, not array. */
 export function trackInteraction(slideId, interactionId, completed, correct) {
     if (!slideId || !interactionId) return;
+    if (typeof completed !== 'boolean' || typeof correct !== 'boolean') {
+        logger.warn(`[EngagementManager] Ignoring invalid interaction state for ${interactionId}; completed and correct must be booleans`);
+        return;
+    }
     const state = this._getState();
     if (!state[slideId]) return;
     state[slideId].tracked.interactionsCompleted[interactionId] = { completed, correct };
@@ -163,7 +188,7 @@ export function trackInteraction(slideId, interactionId, completed, correct) {
 
 /** Scroll depth — numeric high-water mark, not array/boolean. */
 export function trackScrollDepth(slideId, percentage) {
-    if (!slideId || typeof percentage !== 'number') return;
+    if (!slideId || !Number.isFinite(percentage)) return;
     const state = this._getState();
     if (!state[slideId]) return;
     const currentDepth = state[slideId].tracked.scrollDepth;

package/framework/js/engagement/requirement-strategies.js

@@ -250,7 +250,11 @@ export default strategies;
 export const validTypes = Object.keys(strategies);
 
 // ── Core fields not owned by any single strategy ────────────────────
-const CORE_FIELDS = { flipCardsRegistered: [] };
+const CORE_FIELDS = {
+    flipCardsRegistered: [],
+    interactiveImageHotspotsRegistered: [],
+    lightboxesRegistered: []
+};
 
 /**
  * Aggregate all tracked field defaults from strategy declarations.

package/framework/js/main.js

@@ -51,6 +51,12 @@ import { initErrorReporter } from './utilities/error-reporter.js';
 import { initDataReporter, reportData } from './utilities/data-reporter.js';
 import { initCourseChannel } from './utilities/course-channel.js';
 import { canvasSlide } from './utilities/canvas-slide.js';
+import { hydratePortableAssetObject } from './utilities/portable-assets.js';
+
+// Portable exports inject their asset map before this module runs. Hydrating
+// config here covers branding and programmatic media sources before managers
+// cache any paths. This is a no-op in LMS and preview builds.
+hydratePortableAssetObject(courseConfig);
 
 // Expose framework modules globally IMMEDIATELY for bundled course slides
 // This MUST happen before any slide code executes (which happens during glob import)
@@ -615,6 +621,7 @@ async function initializeCourseApplication() {
                     await audioManager.load(slide.audio, toSlideId, 'slide');
                     logger.debug(`[AudioManager] Loaded audio for slide: ${toSlideId}`);
                 } catch (error) {
+                    if (error.name === 'AbortError') return;
                     logger.error(`[AudioManager] Failed to load audio for slide ${toSlideId}:`, error);
                     // Continue - don't let audio errors break navigation
                 }

package/framework/js/managers/assessment-manager.js

@@ -17,6 +17,21 @@
 import { deepMerge } from '../utilities/utilities.js';
 import stateManager from '../state/index.js';
 import { createAssessmentInstance } from '../assessment/AssessmentFactory.js';
+
+/**
+ * Resolves the runtime assessment ID from a derived slide entry or a raw
+ * course-structure entry. CourseHelpers normally supplies assessmentId from
+ * the assessment module; slide.id is the documented authoring fallback.
+ * @param {object} slide
+ * @returns {string}
+ */
+export function resolveAssessmentId(slide) {
+    const assessmentId = slide?.assessmentId || slide?.id;
+    if (!assessmentId || typeof assessmentId !== 'string') {
+        throw new Error('AssessmentManager: assessment slide requires assessmentId or id');
+    }
+    return assessmentId;
+}
 import { logger } from '../utilities/logger.js';
 
 /**
@@ -190,7 +205,7 @@ export function allAssessmentsMeetRequirements(assessmentSlides = []) {
     }
 
     return assessmentsWithRequirements.every(slide =>
-        meetsCompletionRequirements(slide.assessmentId, slide.assessment.completionRequirements)
+        meetsCompletionRequirements(resolveAssessmentId(slide), slide.assessment.completionRequirements)
     );
 }
 

package/framework/js/managers/audio-manager.js

@@ -18,6 +18,11 @@
 import { eventBus } from '../core/event-bus.js';
 import stateManager from '../state/index.js';
 import { logger } from '../utilities/logger.js';
+import { resolvePortableAssetUrl } from '../utilities/portable-assets.js';
+import {
+    DEFAULT_MEDIA_COMPLETION_THRESHOLD,
+    normalizeCompletionThreshold
+} from '../utilities/media-utils.js';
 
 /**
  * @typedef {Object} AudioState
@@ -42,9 +47,6 @@ import { logger } from '../utilities/logger.js';
  * @property {number} [completionThreshold=0.95] - Percentage (0-1) required for completion
  */
 
-/** Default completion threshold (95%) */
-const DEFAULT_COMPLETION_THRESHOLD = 0.95;
-
 class AudioManager {
     constructor() {
         /** @type {HTMLAudioElement|null} */
@@ -61,7 +63,7 @@ class AudioManager {
             duration: 0,
             volume: 1,
             required: false,
-            completionThreshold: DEFAULT_COMPLETION_THRESHOLD,
+            completionThreshold: DEFAULT_MEDIA_COMPLETION_THRESHOLD,
             isCompleted: false
         };
         
@@ -85,6 +87,9 @@ class AudioManager {
         
         /** @type {Function|null} - Cleanup function for pending load operation */
         this._pendingLoadCleanup = null;
+
+        /** @type {Function|null} - Rejects a pending load when its source is replaced */
+        this._pendingLoadCancel = null;
     }
 
     /**
@@ -262,7 +267,7 @@ class AudioManager {
         this.state.isPlaying = false;  // Reset - new audio isn't playing
         this.state.position = 0;       // Reset position for new audio
         this.state.required = config.required || false;
-        this.state.completionThreshold = config.completionThreshold ?? DEFAULT_COMPLETION_THRESHOLD;
+        this.state.completionThreshold = normalizeCompletionThreshold(config.completionThreshold);
         this.maxPositionReached = 0;
         
         // Check if already completed (from previous session)
@@ -279,10 +284,7 @@ class AudioManager {
         });
         
         // Clean up any pending load operation before starting new one
-        if (this._pendingLoadCleanup) {
-            this._pendingLoadCleanup();
-            this._pendingLoadCleanup = null;
-        }
+        this._cancelPendingLoad();
         
         // Set flag to ignore MEDIA_ERR_ABORTED during source switch
         this._isSwitchingSource = true;
@@ -353,11 +355,25 @@ class AudioManager {
             const cleanup = () => {
                 this.audio.removeEventListener('canplaythrough', onLoaded);
                 this.audio.removeEventListener('error', onError);
-                this._pendingLoadCleanup = null;
+                if (this._pendingLoadCleanup === cleanup) {
+                    this._pendingLoadCleanup = null;
+                    this._pendingLoadCancel = null;
+                }
+            };
+
+            const cancel = () => {
+                if (resolved) return;
+                resolved = true;
+                this._isSwitchingSource = false;
+                cleanup();
+                const error = new Error(`Audio load cancelled: ${audioSrc}`);
+                error.name = 'AbortError';
+                reject(error);
             };
             
             // Store cleanup function so it can be called if load is cancelled
             this._pendingLoadCleanup = cleanup;
+            this._pendingLoadCancel = cancel;
             
             // Add event listeners BEFORE setting src
             this.audio.addEventListener('canplaythrough', onLoaded);
@@ -455,6 +471,10 @@ class AudioManager {
      */
     seek(position) {
         this._requireInitialized();
+
+        if (!Number.isFinite(position)) {
+            throw new Error(`AudioManager.seek: position must be a finite number, got ${position}`);
+        }
         
         if (!this.state.currentSrc || !this.audio.duration) {
             return;
@@ -533,10 +553,7 @@ class AudioManager {
         this._savePosition();
         
         // Clean up any pending load operation
-        if (this._pendingLoadCleanup) {
-            this._pendingLoadCleanup();
-            this._pendingLoadCleanup = null;
-        }
+        this._cancelPendingLoad();
         
         // Save contextType before clearing state (needed for event)
         const contextType = this.state.contextType;
@@ -569,7 +586,7 @@ class AudioManager {
             duration: 0,
             volume: this.state.volume,
             required: false,
-            completionThreshold: DEFAULT_COMPLETION_THRESHOLD,
+            completionThreshold: DEFAULT_MEDIA_COMPLETION_THRESHOLD,
             isCompleted: false
         };
         this.maxPositionReached = 0;
@@ -578,6 +595,20 @@ class AudioManager {
         eventBus.emit('audio:unloaded', { contextType });
     }
 
+    /**
+     * Settles and cleans up an in-progress load before replacing its source.
+     * @private
+     */
+    _cancelPendingLoad() {
+        if (this._pendingLoadCancel) {
+            this._pendingLoadCancel();
+        } else if (this._pendingLoadCleanup) {
+            this._pendingLoadCleanup();
+            this._pendingLoadCleanup = null;
+        }
+        this._pendingLoadCancel = null;
+    }
+
     /**
      * Gets the current audio state.
      * @returns {AudioState}
@@ -679,6 +710,9 @@ class AudioManager {
                 }
             }
         }
+
+        const portableSrc = resolvePortableAssetUrl(resolvedSrc);
+        if (portableSrc !== resolvedSrc) return portableSrc;
         
         // If already a full path or URL, return as-is
         if (resolvedSrc.startsWith('http') || resolvedSrc.startsWith('/') || resolvedSrc.startsWith('./')) {
@@ -760,7 +794,7 @@ class AudioManager {
      * @private
      */
     _savePosition() {
-        if (!this.state.contextId || !this.state.position) return;
+        if (!this.state.contextId || !Number.isFinite(this.state.position)) return;
         
         this.positionCache.set(this.state.contextId, this.state.position);
         this._persistPositions();

package/framework/js/managers/flag-manager.js

@@ -48,6 +48,7 @@ class FlagManager {
      * @returns {any} The value of the flag, or undefined if not found.
      */
     getFlag(key) {
+        if (!Object.hasOwn(this.flags, key)) return undefined;
         const val = this.flags[key];
         return (val && typeof val === 'object') ? deepClone(val) : val;
     }
@@ -62,6 +63,9 @@ class FlagManager {
         if (typeof key !== 'string' || key.trim() === '') {
             throw new Error('FlagManager: setFlag requires a non-empty string key.');
         }
+        if (key === '__proto__' || key === 'prototype' || key === 'constructor') {
+            throw new Error(`FlagManager: reserved flag key "${key}" is not allowed.`);
+        }
 
         this.flags[key] = value;
 
@@ -74,7 +78,7 @@ class FlagManager {
      * @param {string} key - The key for the flag to remove.
      */
     removeFlag(key) {
-        if (this.flags.hasOwnProperty(key)) {
+        if (Object.hasOwn(this.flags, key)) {
             delete this.flags[key];
             stateManager.setDomainState(this.DOMAIN_KEY, this.flags, { source: this.SOURCE });
             eventBus.emit('flag:removed', { key });

package/framework/js/managers/objective-manager.js

@@ -147,6 +147,15 @@ class ObjectiveManager {
             }
         }
 
+        if (objectiveData.success_status !== undefined &&
+            !ObjectiveManager.VALID_SUCCESS_STATUSES.includes(objectiveData.success_status)) {
+            throw new Error(`ObjectiveManager: Invalid success_status "${objectiveData.success_status}". Must be one of: ${ObjectiveManager.VALID_SUCCESS_STATUSES.join(', ')}`);
+        }
+        if (objectiveData.completion_status !== undefined &&
+            !ObjectiveManager.VALID_COMPLETION_STATUSES.includes(objectiveData.completion_status)) {
+            throw new Error(`ObjectiveManager: Invalid completion_status "${objectiveData.completion_status}". Must be one of: ${ObjectiveManager.VALID_COMPLETION_STATUSES.join(', ')}`);
+        }
+
         const existing = this.objectives[id] || { id };
         const updated = { ...existing, ...objectiveData };
 
@@ -178,7 +187,7 @@ class ObjectiveManager {
      * Valid completion status values per SCORM spec.
      * @private
      */
-    static VALID_COMPLETION_STATUSES = ['completed', 'incomplete'];
+    static VALID_COMPLETION_STATUSES = ['completed', 'incomplete', 'not attempted', 'unknown'];
 
     /**
      * A helper method to specifically update the success status of an objective.
@@ -200,12 +209,11 @@ class ObjectiveManager {
         if (!objective) {
             throw new Error(`ObjectiveManager: Objective with id "${id}" not found.`);
         }
-        objective.success_status = success_status;
-        this.setObjective(objective);
-        if (score !== null) {
-            // Validate score through setScore's guard (which will persist separately)
-            this.setScore(id, score);
-        }
+        this.setObjective({
+            ...objective,
+            success_status,
+            ...(score !== null ? { score } : {})
+        });
     }
 
     /**

package/framework/js/managers/score-manager.js

@@ -100,10 +100,24 @@ class ScoreManager {
             throw new Error('[ScoreManager] Configuration must include non-empty "sources" array');
         }
 
+        const sourceIds = config.sources.map(source =>
+            typeof source === 'string' ? source : source?.id
+        );
+        const invalidSourceId = sourceIds.find(sourceId =>
+            typeof sourceId !== 'string' || !/^(assessment|objective):.+/.test(sourceId)
+        );
+        if (invalidSourceId !== undefined) {
+            throw new Error(`[ScoreManager] Invalid source ID "${invalidSourceId}". Use "assessment:<id>" or "objective:<id>".`);
+        }
+        if (new Set(sourceIds).size !== sourceIds.length) {
+            throw new Error('[ScoreManager] Scoring source IDs must be unique');
+        }
+
         // Validate weighted sources
         if (config.type === 'weighted') {
             const hasInvalidSources = config.sources.some(source => 
-                typeof source !== 'object' || !source.id || typeof source.weight !== 'number'
+                !source || typeof source !== 'object' || !source.id ||
+                !Number.isFinite(source.weight) || source.weight < 0 || source.weight > 1
             );
             if (hasInvalidSources) {
                 throw new Error('[ScoreManager] Weighted scoring requires sources with {id, weight} format');
@@ -167,7 +181,7 @@ class ScoreManager {
                 // Load objective score from ObjectiveManager
                 try {
                     const objective = objectiveManager.getObjective(id);
-                    if (objective && typeof objective.score === 'number') {
+                    if (objective && Number.isFinite(objective.score) && objective.score >= 0 && objective.score <= 100) {
                         this.cachedScores[sourceId] = objective.score;
                     }
                 } catch (_error) {
@@ -179,7 +193,10 @@ class ScoreManager {
                     const domainKey = `assessment_${id}`;
                     const assessmentState = stateManager.getDomainState(domainKey);
                     const summary = assessmentState?.summary;
-                    if (summary && summary.lastResults && typeof summary.lastResults.scorePercentage === 'number') {
+                    if (summary && summary.lastResults &&
+                        Number.isFinite(summary.lastResults.scorePercentage) &&
+                        summary.lastResults.scorePercentage >= 0 &&
+                        summary.lastResults.scorePercentage <= 100) {
                         this.cachedScores[sourceId] = summary.lastResults.scorePercentage;
                     }
                 } catch (_error) {
@@ -200,6 +217,10 @@ class ScoreManager {
     _updateSourceScore(sourceId, score) {
         if (!this.isInitialized) return;
 
+        if (!Number.isFinite(score) || score < 0 || score > 100) {
+            throw new Error(`[ScoreManager] Source score ${score} is out of range [0-100].`);
+        }
+
         // Check if this source is configured
         const sourceIds = this.config.sources.map(source => 
             typeof source === 'string' ? source : source.id
@@ -213,7 +234,7 @@ class ScoreManager {
         const oldScore = this.cachedScores[sourceId];
         this.cachedScores[sourceId] = score;
         
-        logger.debug(`[ScoreManager] Score updated: ${sourceId} = ${score} (was ${oldScore || 'none'})`);
+        logger.debug(`[ScoreManager] Score updated: ${sourceId} = ${score} (was ${oldScore ?? 'none'})`);
 
         // Recalculate and report course score
         this._calculateAndReportScore();
@@ -234,7 +255,7 @@ class ScoreManager {
         }
 
         // Validate score range
-        if (calculatedScore < 0 || calculatedScore > 100 || isNaN(calculatedScore)) {
+        if (!Number.isFinite(calculatedScore) || calculatedScore < 0 || calculatedScore > 100) {
             throw new Error(`[ScoreManager] Calculated score ${calculatedScore} is out of range [0-100]. This indicates a bug in the scoring calculation.`);
         }
 
@@ -381,7 +402,7 @@ class ScoreManager {
                 return null;
             }
 
-            if (typeof result !== 'number' || isNaN(result)) {
+            if (!Number.isFinite(result)) {
                 throw new Error(`[ScoreManager] Custom calculate function must return a number or null. Got: ${typeof result}`);
             }