coursecode 0.1.57 → 0.1.59

package/framework/js/components/ui-components/interactive-image.js

@@ -51,21 +51,14 @@ export function init(root, _options = {}) {
     const currentSlideId = NavigationState.getCurrentSlideId();
     const imageId = container.id || `interactive-image-${Math.random().toString(36).substr(2, 9)}`;
     const accordionId = container.dataset.accordionId;
-
-    // Register with EngagementManager if on a slide
-    if (currentSlideId) {
-        const hotspotIds = hotspots.map(h => h.dataset.hotspotId);
-        if (typeof engagementManager.registerInteractiveImage === 'function') {
-            engagementManager.registerInteractiveImage(currentSlideId, hotspotIds);
-        }
-    }
+    const cleanups = [];
 
     // Setup Accordion Integration if ID is provided
     let accordionElement = null;
     if (accordionId) {
         accordionElement = document.getElementById(accordionId);
         if (accordionElement) {
-            setupAccordionIntegration(container, hotspots, accordionElement, accordionId);
+            cleanups.push(setupAccordionIntegration(hotspots, accordionElement, accordionId));
         } else {
             logger.warn(`[InteractiveImage] Accordion #${accordionId} not found for image ${imageId}`);
         }
@@ -113,21 +106,30 @@ export function init(root, _options = {}) {
             }
         };
 
-        hotspot.addEventListener('click', handleClick);
-        hotspot.addEventListener('keydown', (e) => {
+        const handleKeydown = (e) => {
             if (e.key === 'Enter' || e.key === ' ') {
                 handleClick(e);
             }
+        };
+
+        hotspot.addEventListener('click', handleClick);
+        hotspot.addEventListener('keydown', handleKeydown);
+        cleanups.push(() => {
+            hotspot.removeEventListener('click', handleClick);
+            hotspot.removeEventListener('keydown', handleKeydown);
         });
     });
 
     logger.debug(`[InteractiveImage] Initialized ${hotspots.length} hotspots for ${imageId}`);
+    return {
+        destroy: () => cleanups.forEach(cleanup => cleanup())
+    };
 }
 
 /**
  * Sets up bi-directional sync between image hotspots and accordion panels.
  */
-function setupAccordionIntegration(imageContainer, hotspots, accordionElement, accordionId) {
+function setupAccordionIntegration(hotspots, accordionElement, accordionId) {
     // Map hotspots by ID for quick access
     const hotspotMap = new Map(hotspots.map(h => [h.dataset.hotspotId, h]));
 
@@ -156,25 +158,23 @@ function setupAccordionIntegration(imageContainer, hotspots, accordionElement, a
 
     // 2. Hover Effects (Accordion Button -> Image Hotspot)
     const buttons = accordionElement.querySelectorAll('[data-panel]');
+    const buttonCleanups = [];
     buttons.forEach(btn => {
         const panelId = btn.dataset.panel;
         const hotspot = hotspotMap.get(panelId);
 
         if (hotspot) {
-            btn.addEventListener('mouseenter', () => {
-                hotspot.classList.add('highlighted');
-            });
-
-            btn.addEventListener('mouseleave', () => {
-                hotspot.classList.remove('highlighted');
-            });
-
-            btn.addEventListener('focus', () => {
-                hotspot.classList.add('highlighted');
-            });
-
-            btn.addEventListener('blur', () => {
-                hotspot.classList.remove('highlighted');
+            const highlight = () => hotspot.classList.add('highlighted');
+            const unhighlight = () => hotspot.classList.remove('highlighted');
+            btn.addEventListener('mouseenter', highlight);
+            btn.addEventListener('mouseleave', unhighlight);
+            btn.addEventListener('focus', highlight);
+            btn.addEventListener('blur', unhighlight);
+            buttonCleanups.push(() => {
+                btn.removeEventListener('mouseenter', highlight);
+                btn.removeEventListener('mouseleave', unhighlight);
+                btn.removeEventListener('focus', highlight);
+                btn.removeEventListener('blur', unhighlight);
             });
         }
     });
@@ -196,40 +196,16 @@ function setupAccordionIntegration(imageContainer, hotspots, accordionElement, a
         }
     };
 
-    // Component lifecycle cleanup using MutationObserver
-    // When the container is removed from DOM, we automatically clean up all listeners
     const cleanupListeners = () => {
         document.removeEventListener('click', safeHandleOutsideClick);
         eventBus.off('accordion:toggled', handleAccordionToggle);
-        if (observer) {
-            observer.disconnect();
-        }
+        buttonCleanups.forEach(cleanup => cleanup());
     };
 
     const safeHandleOutsideClick = (e) => {
-        if (!document.body.contains(imageContainer)) {
-            cleanupListeners();
-            return;
-        }
         handleOutsideClick(e);
     };
 
-    // Use MutationObserver to detect when container is removed from DOM
-    const observer = new MutationObserver((mutations) => {
-        for (const mutation of mutations) {
-            for (const node of mutation.removedNodes) {
-                if (node === imageContainer || node.contains?.(imageContainer)) {
-                    cleanupListeners();
-                    return;
-                }
-            }
-        }
-    });
-
-    // Observe parent for child removals (handles SPA navigation cleanup)
-    if (imageContainer.parentNode) {
-        observer.observe(imageContainer.parentNode, { childList: true });
-    }
-
     document.addEventListener('click', safeHandleOutsideClick);
+    return cleanupListeners;
 }

package/framework/js/components/ui-components/lightbox.js

@@ -65,7 +65,7 @@ export const schema = {
 export const metadata = {
     category: 'ui-component',
     cssFile: 'components/lightbox.css',
-    engagementTracking: 'viewAllLightbox',
+    engagementTracking: 'viewAllLightboxes',
     emitsEvents: ['lightbox:opened', 'lightbox:closed']
 };
 
@@ -75,6 +75,7 @@ import { logger } from '../../utilities/logger.js';
 import { escapeHTML } from '../../utilities/utilities.js';
 import { fetchAndRenderMarkdown } from '../../utilities/markdown-renderer.js';
 import engagementManager from '../../engagement/engagement-manager.js';
+import { resolvePortableAssetUrl } from '../../utilities/portable-assets.js';
 
 // Lightbox state
 let lightboxElement = null;
@@ -91,6 +92,8 @@ let currentMediaType = 'image'; // 'image' | 'video' | 'markdown' | 'pdf'
  */
 function _resolvePath(src) {
     if (!src) return src;
+    const portableSrc = resolvePortableAssetUrl(src);
+    if (portableSrc !== src) return portableSrc;
     // Already absolute URL or protocol-relative
     if (src.startsWith('http://') || src.startsWith('https://') || src.startsWith('//')) {
         return src;
@@ -104,7 +107,7 @@ function _resolvePath(src) {
         return src;
     }
     // Otherwise, assume relative to course/ directory
-    return `./course/${src}`;
+    return resolvePortableAssetUrl(`./course/${src}`);
 }
 
 /**
@@ -129,6 +132,7 @@ function getTriggerSrc(trigger) {
  */
 function detectPDF(url) {
     if (!url) return null;
+    if (url.startsWith('data:application/pdf')) return { type: 'pdf' };
     if (/\.pdf($|\?|#)/i.test(url)) return { type: 'pdf' };
     return null;
 }
@@ -140,6 +144,7 @@ function detectPDF(url) {
  */
 function detectMarkdown(url) {
     if (!url) return null;
+    if (url.startsWith('data:text/markdown')) return { type: 'markdown' };
     if (/\.md($|\?|#)/i.test(url)) return { type: 'markdown' };
     return null;
 }
@@ -182,6 +187,7 @@ function detectVimeo(url) {
  */
 function detectNativeVideo(url) {
     if (!url) return null;
+    if (url.startsWith('data:video/')) return { type: 'native' };
     const videoExtensions = /\.(mp4|webm|ogg|mov|m4v)($|\?)/i;
     if (videoExtensions.test(url)) return { type: 'native' };
     return null;
@@ -211,10 +217,11 @@ export function init(element) {
         createLightboxElement();
     }
 
-    element.addEventListener('click', (e) => {
+    const handleClick = (e) => {
         e.preventDefault();
         openFromTrigger(element);
-    });
+    };
+    element.addEventListener('click', handleClick);
 
     const src = getTriggerSrc(element);
     const mediaType = getMediaType(src);
@@ -239,6 +246,14 @@ export function init(element) {
     if (subtitle) {
         wrapTriggerWithSubtitle(element, subtitle);
     }
+
+    return {
+        destroy: () => {
+            element.removeEventListener('click', handleClick);
+            delete element.dataset.lightboxInitialized;
+            if (isOpen) close();
+        }
+    };
 }
 
 /**
@@ -649,4 +664,3 @@ function navigate(direction) {
 export function isVisible() {
     return isOpen;
 }
-

package/framework/js/components/ui-components/modal.js

@@ -40,6 +40,7 @@ import * as NavigationState from '../../navigation/NavigationState.js';
 import * as AudioPlayer from './audio-player.js';
 import { eventBus } from '../../core/event-bus.js';
 import { logger } from '../../utilities/logger.js';
+import { normalizeCompletionThreshold } from '../../utilities/media-utils.js';
 import { renderCompactPlayer } from './audio-player.js';
 
 // Schema for validation, linting, and AI-assisted authoring
@@ -144,7 +145,7 @@ export function setup() {
  * @param {HTMLElement} trigger 
  */
 export function init(trigger) {
-    trigger.addEventListener('click', () => {
+    const handleClick = () => {
         const title = trigger.dataset.title || 'Modal';
         let body = trigger.dataset.body || '';
         let footer = trigger.dataset.footer || '<button class="btn btn-secondary" data-action="close-modal">Close</button>';
@@ -183,7 +184,7 @@ export function init(trigger) {
             src: audioSrc,
             autoplay: trigger.dataset.audioAutoplay === 'true',
             required: trigger.dataset.audioRequired === 'true',
-            completionThreshold: parseFloat(trigger.dataset.audioThreshold) || 0.95
+            completionThreshold: normalizeCompletionThreshold(trigger.dataset.audioThreshold)
         } : null;
 
         // Get modal ID for tracking (from trigger id or generate one)
@@ -200,7 +201,15 @@ export function init(trigger) {
                 closeOnEscape: trigger.dataset.closeOnEscape !== 'false'
             }
         });
-    });
+    };
+
+    trigger.addEventListener('click', handleClick);
+    return {
+        destroy: () => {
+            trigger.removeEventListener('click', handleClick);
+            if (isVisible()) hide();
+        }
+    };
 }
 
 /**
@@ -275,13 +284,15 @@ export async function show({ title, body, footer = '', modalId = null, config =
     // (enforced by runtime-linter - a slide cannot have both)
     if (audioManager.isReady() && audio && audio.src) {
         const audioContextId = `modal-${currentModalId}`;
+        let modalAudioLoaded = false;
         try {
             await audioManager.load({
                 src: audio.src,
                 autoplay: audio.autoplay === true,
                 required: audio.required || false,
-                completionThreshold: audio.completionThreshold || 0.95
+                completionThreshold: normalizeCompletionThreshold(audio.completionThreshold)
             }, audioContextId, 'modal');
+            modalAudioLoaded = true;
 
             logger.debug(`[Modal] Loaded modal audio: ${audioContextId}`);
 
@@ -290,11 +301,13 @@ export async function show({ title, body, footer = '', modalId = null, config =
                 AudioPlayer.initAudioControlsInContainer(modalFooter);
             }
         } catch (err) {
-            logger.warn('[Modal] Failed to load modal audio:', err.message);
+            if (err.name !== 'AbortError') {
+                logger.warn('[Modal] Failed to load modal audio:', err.message);
+            }
         }
 
         // If audio is required, listen for completion
-        if (audio.required) {
+        if (audio.required && modalAudioLoaded) {
             audioCompletedHandler = ({ contextId }) => {
                 if (contextId === audioContextId && currentSlideId) {
                     engagementManager.trackModalAudioComplete(currentSlideId, currentModalId);
@@ -383,4 +396,4 @@ export function hide() {
     activeConfig = {};
 
     announceToScreenReader('Modal closed');
-}
+}

package/framework/js/components/ui-components/notifications.js

@@ -60,16 +60,21 @@ export function setup() {
  * Initializes declarative notification triggers in a container using event delegation.
  * @param {HTMLElement} container
  */
-export function init(container) {
+export function initNotificationTriggers(container) {
     // Use event delegation to handle dynamically rendered content
-    container.addEventListener('click', (event) => {
+    const handleClick = (event) => {
         const trigger = event.target.closest('[data-action="show-notification"]');
         if (trigger) {
             const type = trigger.dataset.type || 'info';
             const message = trigger.dataset.message || 'Notification';
             showNotification(message, type);
         }
-    });
+    };
+    container.addEventListener('click', handleClick);
+
+    return {
+        destroy: () => container.removeEventListener('click', handleClick)
+    };
 }
 
 export function showNotification(message, type = 'info', duration = 5000, options = {}) {

package/framework/js/components/ui-components/video-player.js

@@ -54,6 +54,8 @@ import engagementManager from '../../engagement/engagement-manager.js';
 import * as NavigationState from '../../navigation/NavigationState.js';
 import { logger } from '../../utilities/logger.js';
 import { iconManager } from '../../utilities/icons.js';
+import { normalizeCompletionThreshold } from '../../utilities/media-utils.js';
+import { resolvePortableAssetUrl } from '../../utilities/portable-assets.js';
 
 /** @type {Map<string, VideoPlayer>} Active player instances */
 const playerInstances = new Map();
@@ -131,10 +133,12 @@ function detectExternalVideo(url) {
  * @returns {string} Resolved path
  */
 function resolvePath(src) {
+    const portableSrc = resolvePortableAssetUrl(src);
+    if (portableSrc !== src) return portableSrc;
     if (src.startsWith('http') || src.startsWith('/') || src.startsWith('./')) {
         return src;
     }
-    return `./course/assets/${src}`;
+    return resolvePortableAssetUrl(`./course/assets/${src}`);
 }
 
 /**
@@ -148,7 +152,7 @@ class VideoPlayer {
         this.posterSrc = container.dataset.videoPoster;
         this.captionsSrc = container.dataset.videoCaptions;
         this.required = container.dataset.videoRequired === 'true';
-        this.threshold = parseFloat(container.dataset.videoThreshold) || 0.95;
+        this.threshold = normalizeCompletionThreshold(container.dataset.videoThreshold);
         this.autoplay = container.dataset.videoAutoplay === 'true';
 
         if (!this.videoId) {
@@ -167,6 +171,18 @@ class VideoPlayer {
         this.iframe = null;     // External video iframe
         this.elements = {};
         this.eventHandlers = {};
+        this.domEventHandlers = {
+            click: this._handleClick.bind(this),
+            progressKeydown: this._handleProgressKeydown.bind(this),
+            progressMousedown: this._handleProgressMousedown.bind(this),
+            fullscreenChange: this._handleFullscreenChange.bind(this),
+            videoDoubleClick: () => this._toggleFullscreen(),
+            overlayClick: (event) => {
+                event.stopPropagation();
+                this._togglePlayPause();
+            }
+        };
+        this.dragCleanup = null;
         this.isFullscreen = false;
 
         this._render();
@@ -311,35 +327,32 @@ class VideoPlayer {
         // External videos use platform's native controls
         if (this.isExternal) {
             // Only fullscreen detection for wrapper
-            document.addEventListener('fullscreenchange', this._handleFullscreenChange.bind(this));
-            document.addEventListener('webkitfullscreenchange', this._handleFullscreenChange.bind(this));
+            document.addEventListener('fullscreenchange', this.domEventHandlers.fullscreenChange);
+            document.addEventListener('webkitfullscreenchange', this.domEventHandlers.fullscreenChange);
             return;
         }
 
         // Control bar click delegation
-        this.container.addEventListener('click', this._handleClick.bind(this));
+        this.container.addEventListener('click', this.domEventHandlers.click);
 
         // Progress bar interactions
         if (this.elements.progressBar) {
-            this.elements.progressBar.addEventListener('keydown', this._handleProgressKeydown.bind(this));
-            this.elements.progressBar.addEventListener('mousedown', this._handleProgressMousedown.bind(this));
+            this.elements.progressBar.addEventListener('keydown', this.domEventHandlers.progressKeydown);
+            this.elements.progressBar.addEventListener('mousedown', this.domEventHandlers.progressMousedown);
         }
 
         // Fullscreen change detection
-        document.addEventListener('fullscreenchange', this._handleFullscreenChange.bind(this));
-        document.addEventListener('webkitfullscreenchange', this._handleFullscreenChange.bind(this));
+        document.addEventListener('fullscreenchange', this.domEventHandlers.fullscreenChange);
+        document.addEventListener('webkitfullscreenchange', this.domEventHandlers.fullscreenChange);
 
         // Double-click video to toggle fullscreen
         if (this.video) {
-            this.video.addEventListener('dblclick', () => this._toggleFullscreen());
+            this.video.addEventListener('dblclick', this.domEventHandlers.videoDoubleClick);
         }
 
         // Click overlay to play
         if (this.elements.overlay) {
-            this.elements.overlay.addEventListener('click', (e) => {
-                e.stopPropagation();
-                this._togglePlayPause();
-            });
+            this.elements.overlay.addEventListener('click', this.domEventHandlers.overlayClick);
         }
     }
 
@@ -447,8 +460,11 @@ class VideoPlayer {
     _handleProgressMousedown(event) {
         if (!this.video || !this.video.duration) return;
 
+        this.dragCleanup?.();
+
         const progressBar = this.elements.progressBar;
         const rect = progressBar.getBoundingClientRect();
+        if (rect.width <= 0) return;
 
         const seek = (clientX) => {
             const pct = Math.max(0, Math.min(100, ((clientX - rect.left) / rect.width) * 100));
@@ -458,15 +474,19 @@ class VideoPlayer {
         seek(event.clientX);
 
         const onMouseMove = (e) => seek(e.clientX);
-        const onMouseUp = () => {
+        const cleanupDrag = () => {
             document.removeEventListener('mousemove', onMouseMove);
-            document.removeEventListener('mouseup', onMouseUp);
+            document.removeEventListener('mouseup', cleanupDrag);
             progressBar.classList.remove('dragging');
+            if (this.dragCleanup === cleanupDrag) {
+                this.dragCleanup = null;
+            }
         };
 
         progressBar.classList.add('dragging');
         document.addEventListener('mousemove', onMouseMove);
-        document.addEventListener('mouseup', onMouseUp);
+        document.addEventListener('mouseup', cleanupDrag);
+        this.dragCleanup = cleanupDrag;
     }
 
     _attachToManager() {
@@ -605,6 +625,8 @@ class VideoPlayer {
     }
 
     destroy() {
+        this.dragCleanup?.();
+
         // Unsubscribe from events
         eventBus.off('video:loaded', this.eventHandlers.loaded);
         eventBus.off('video:play', this.eventHandlers.play);
@@ -616,11 +638,15 @@ class VideoPlayer {
         // Detach from manager
         if (this.video) {
             videoManager.detachVideo(this.video);
+            this.video.removeEventListener('dblclick', this.domEventHandlers.videoDoubleClick);
         }
 
-        // Remove fullscreen listeners
-        document.removeEventListener('fullscreenchange', this._handleFullscreenChange);
-        document.removeEventListener('webkitfullscreenchange', this._handleFullscreenChange);
+        this.container.removeEventListener('click', this.domEventHandlers.click);
+        this.elements.progressBar?.removeEventListener('keydown', this.domEventHandlers.progressKeydown);
+        this.elements.progressBar?.removeEventListener('mousedown', this.domEventHandlers.progressMousedown);
+        this.elements.overlay?.removeEventListener('click', this.domEventHandlers.overlayClick);
+        document.removeEventListener('fullscreenchange', this.domEventHandlers.fullscreenChange);
+        document.removeEventListener('webkitfullscreenchange', this.domEventHandlers.fullscreenChange);
 
         playerInstances.delete(this.videoId);
         logger.debug(`[VideoPlayer] Destroyed: ${this.videoId}`);

package/framework/js/core/event-bus.js

@@ -137,16 +137,16 @@ class EventBus {
 
       // Create a copy of listeners to avoid issues if listeners modify the array
       const listeners = [...this.events[event]];
-      const onceListeners = [];
 
       listeners.forEach(listener => {
+        // Remove one-shot listeners before invocation so thrown callbacks and
+        // re-entrant emits cannot execute them more than once.
+        if (listener.once) {
+          this.off(event, listener.id);
+        }
+
         try {
           listener.callback(data);
-
-          // Track once listeners for removal
-          if (listener.once) {
-            onceListeners.push(listener.id);
-          }
         } catch (error) {
           // Log the error but don't break other listeners — use safeStringify
           // to prevent a secondary cascade from unserializable error objects
@@ -154,8 +154,6 @@ class EventBus {
         }
       });
 
-      // Remove once listeners
-      onceListeners.forEach(id => this.off(event, id));
     } finally {
       if (isErrorEvent) {
         this._emittingError = false;
@@ -177,37 +175,42 @@ class EventBus {
     const hasListeners = Boolean(this.events[event]?.length);
     if (!isErrorEvent && !hasListeners) return false;
 
+    if (isErrorEvent && this._emittingError) {
+      logger.warn(`[EventBus] Suppressed recursive error event: ${event}`);
+      return false;
+    }
+
     if (isErrorEvent) {
-      if (this._emittingError) {
-        logger.warn(`[EventBus] Suppressed recursive error event: ${event}`);
-        return false;
-      }
       this._emittingError = true;
-      logger.error(`[EventBus Error] ${event}:`, safeStringify(data));
-      this._emittingError = false;
     }
 
-    if (!hasListeners) return false;
+    try {
+      if (isErrorEvent) {
+        logger.error(`[EventBus Error] ${event}:`, safeStringify(data));
+      }
 
-    const listeners = [...this.events[event]];
-    const onceListeners = [];
+      if (!hasListeners) return false;
 
-    for (const listener of listeners) {
-      try {
-        await listener.callback(data);
+      const listeners = [...this.events[event]];
 
+      for (const listener of listeners) {
         if (listener.once) {
-          onceListeners.push(listener.id);
+          this.off(event, listener.id);
         }
-      } catch (error) {
-        logger.error(`[EventBus] Error in async listener for '${event}':`, error);
-      }
-    }
 
-    // Remove once listeners
-    onceListeners.forEach(id => this.off(event, id));
+        try {
+          await listener.callback(data);
+        } catch (error) {
+          logger.error(`[EventBus] Error in async listener for '${event}':`, error);
+        }
+      }
 
-    return true;
+      return true;
+    } finally {
+      if (isErrorEvent) {
+        this._emittingError = false;
+      }
+    }
   }
 
   /**

package/framework/js/dev/runtime-linter.js

@@ -42,7 +42,7 @@ const DYNAMIC_CLASSES = new Set([
     // Component-internal classes — styled via [data-component] selectors in individual component CSS files
     'intro-card', 'card-icon',
     // Interaction-internal classes — used by interaction JS for DOM structure
-    'drag-drop', 'matching-items', 'matching-targets',
+    'drag-drop', 'matching-items', 'matching-targets', 'image-container', 'hotspot-feedback',
     // Slide-specific JS selectors — queried by slide scripts for event binding
     'resources', 'complete-remedial-btn',
 ]);
@@ -833,6 +833,7 @@ function validateVisualLayout(slideId, renderedContent, errors, warnings) {
         const textElements = renderedContent.querySelectorAll('p, span:not(.accordion-icon), li, a, h1, h2, h3, h4, h5, h6, button');
         for (const el of textElements) {
             if (isLintIgnored(el, 'contrast')) continue;
+            if (el.classList.contains('sr-only') || el.closest('.sr-only')) continue;
             // Skip elements that are not visible or have no text
             if (el.offsetParent === null || el.textContent.trim() === '') continue;
 
@@ -1042,7 +1043,8 @@ function validateTextProximityToVisualElements(slideId, renderedContent, warning
         'dropdown', 'dropdown-menu', 'dropdown-item',
         'table',  // Tables manage their own cell spacing
         'step-number', 'step-content', 'step',  // Pattern-steps elements have intentional circular styling
-        'btn-link'  // Link-styled button intentionally has minimal padding
+        'btn-link',  // Link-styled button intentionally has minimal padding
+        'hotspot-area', 'interactive-image-hotspot'
     ]);
 
     // HTML elements that manage their own spacing (exclude from checks)
@@ -1171,6 +1173,8 @@ function validateElementOverlap(slideId, renderedContent, warnings) {
     const absoluteElements = renderedContent.querySelectorAll('[style*="position:absolute"], [style*="position: absolute"]');
     for (const el of absoluteElements) {
         if (el.offsetParent === null) continue;
+        // Hotspots intentionally overlap their background image and sometimes each other.
+        if (el.matches('[data-hotspot-id], .hotspot-area, .interactive-image-hotspot')) continue;
 
         const rect = el.getBoundingClientRect();
         const elText = el.textContent.trim().substring(0, 30);