coursecode 0.1.0

package/framework/js/utilities/error-reporter.js

@@ -0,0 +1,313 @@
+/**
+ * Error Reporter - Optional external error reporting via webhook
+ * 
+ * Sends framework errors to a configured endpoint (e.g., Cloudflare Worker)
+ * for email notifications. Disabled by default; enable in course-config.js.
+ * 
+ * Flood protection:
+ *   - Per-error dedup: same error key won't be sent twice within 60 seconds
+ *   - Batching: errors arriving within a 2-second window are combined into one request
+ *   - Global rate cap: max 10 reports per rolling 60-second window
+ *   - Re-entrancy guard: reporter's own log messages don't trigger new reports
+ * 
+ * Configuration in course-config.js:
+ *   environment: {
+ *       errorReporting: {
+ *           endpoint: 'https://your-worker.workers.dev/errors',
+ *           // Optional: API key for endpoint authentication
+ *           apiKey: 'your-shared-api-key',
+ *           // Optional: include course/learner context
+ *           includeContext: true
+ *       }
+ *   }
+ */
+
+import { eventBus } from '../core/event-bus.js';
+import { logger } from './logger.js';
+
+// ── Per-error dedup ─────────────────────────────────────────────────
+const recentErrors = new Map();
+const DEBOUNCE_MS = 60000; // Don't send same error more than once per minute
+
+// ── Batching ────────────────────────────────────────────────────────
+const BATCH_WINDOW_MS = 2000; // Collect errors for 2 seconds before sending
+let pendingBatch = [];         // Accumulated payloads waiting to flush
+let batchTimer = null;         // setTimeout handle for the current window
+
+// ── Global rate cap ─────────────────────────────────────────────────
+const MAX_SENDS_PER_WINDOW = 10;
+const RATE_WINDOW_MS = 60000;
+const sendTimestamps = [];     // Timestamps of recent sends
+
+// ── Re-entrancy guard ───────────────────────────────────────────────
+let _isReporting = false;
+
+/**
+ * Generate a unique key for an error to detect duplicates
+ */
+function getErrorKey(errorData) {
+    const domain = errorData.domain || 'unknown';
+    const operation = errorData.operation || 'unknown';
+    const message = errorData.message || String(errorData);
+    return `${domain}:${operation}:${message}`;
+}
+
+/**
+ * Check if this error was recently reported
+ */
+function wasRecentlyReported(errorKey) {
+    const lastReported = recentErrors.get(errorKey);
+    if (!lastReported) return false;
+    return (Date.now() - lastReported) < DEBOUNCE_MS;
+}
+
+/**
+ * Mark an error as recently reported
+ */
+function markAsReported(errorKey) {
+    recentErrors.set(errorKey, Date.now());
+    
+    // Clean up old entries periodically
+    if (recentErrors.size > 100) {
+        const now = Date.now();
+        for (const [key, timestamp] of recentErrors.entries()) {
+            if (now - timestamp > DEBOUNCE_MS) {
+                recentErrors.delete(key);
+            }
+        }
+    }
+}
+
+/**
+ * Check whether we've hit the global rate cap
+ */
+function isRateLimited() {
+    const now = Date.now();
+    // Prune timestamps outside the rolling window
+    while (sendTimestamps.length > 0 && now - sendTimestamps[0] > RATE_WINDOW_MS) {
+        sendTimestamps.shift();
+    }
+    return sendTimestamps.length >= MAX_SENDS_PER_WINDOW;
+}
+
+/**
+ * Queue an error for batched sending.
+ * Errors are collected for BATCH_WINDOW_MS then flushed in a single request.
+ */
+function enqueueError(errorData, config, courseConfig) {
+    // Normalize error data — some emitters pass strings instead of objects
+    const normalizedError = typeof errorData === 'string' 
+        ? { domain: 'unknown', operation: 'unknown', message: errorData }
+        : errorData;
+    
+    // Skip user-facing errors (expected behavior, not system errors)
+    if (normalizedError.userFacing === true) {
+        logger.debug('[ErrorReporter] Skipping user-facing error (not a system error):', normalizedError.message);
+        return;
+    }
+    
+    const errorKey = getErrorKey(normalizedError);
+    
+    // Skip if recently reported (even across batches)
+    if (wasRecentlyReported(errorKey)) {
+        logger.debug('[ErrorReporter] Skipping duplicate error:', errorKey);
+        return;
+    }
+    
+    // Global rate cap check
+    if (isRateLimited()) {
+        logger.debug('[ErrorReporter] Rate limited, dropping error:', errorKey);
+        return;
+    }
+
+    // Build payload entry
+    const payload = {
+        domain: normalizedError.domain || 'unknown',
+        operation: normalizedError.operation || 'unknown',
+        message: normalizedError.message || String(errorData),
+        stack: normalizedError.stack,
+        context: normalizedError.context
+    };
+
+    // Mark as reported immediately so duplicates within the same batch are dropped
+    markAsReported(errorKey);
+
+    pendingBatch.push(payload);
+
+    // Store config/courseConfig for the flush (same for all errors in a session)
+    if (!batchTimer) {
+        batchTimer = setTimeout(() => flushBatch(config, courseConfig), BATCH_WINDOW_MS);
+    }
+}
+
+/**
+ * Flush the pending batch as a single request to the endpoint.
+ */
+async function flushBatch(config, courseConfig) {
+    const batch = pendingBatch;
+    pendingBatch = [];
+    batchTimer = null;
+
+    if (batch.length === 0) return;
+
+    // Build the request payload
+    const request = {
+        // If single error, send flat for backward compatibility; otherwise send array
+        ...(batch.length === 1
+            ? batch[0]
+            : { errors: batch, message: `${batch.length} errors`, domain: batch[0].domain, operation: batch[0].operation }),
+        
+        // Metadata
+        timestamp: new Date().toISOString(),
+        url: window.location.href,
+        userAgent: navigator.userAgent
+    };
+
+    // Optionally include course context
+    if (config.includeContext !== false) {
+        request.course = {
+            title: courseConfig.metadata?.title,
+            version: courseConfig.metadata?.version,
+            id: courseConfig.metadata?.id
+        };
+    }
+
+    // Guard re-entrancy: our own logger calls must not trigger new reports
+    _isReporting = true;
+    try {
+        const headers = { 'Content-Type': 'application/json' };
+        if (config.apiKey) headers['Authorization'] = `Bearer ${config.apiKey}`;
+
+        const response = await fetch(config.endpoint, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(request)
+        });
+
+        if (response.ok) {
+            sendTimestamps.push(Date.now());
+            logger.debug(`[ErrorReporter] Batch of ${batch.length} error(s) reported successfully`);
+        } else {
+            logger.warn('[ErrorReporter] Failed to report error:', response.status);
+        }
+    } catch (e) {
+        // Silent fail — don't break the course or cause infinite loops
+        logger.debug('[ErrorReporter] Network error reporting:', e.message);
+    } finally {
+        _isReporting = false;
+    }
+}
+
+// Store config globally for user reports
+let _config = null;
+let _courseConfig = null;
+
+/**
+ * Check if error reporting is configured and user reports are enabled
+ * @returns {boolean}
+ */
+export function isUserReportingEnabled() {
+    return !!(_config?.endpoint && _config?.enableUserReports !== false);
+}
+
+/**
+ * Submit a user-initiated issue report
+ * @param {string} description - User's description of the issue
+ * @param {Object} options - Additional options
+ * @returns {Promise<{success: boolean, message: string}>}
+ */
+export async function submitUserReport(description, options = {}) {
+    if (!_config?.endpoint) {
+        return { success: false, message: 'Error reporting is not configured.' };
+    }
+    
+    const payload = {
+        type: 'user_report',
+        description: description.trim(),
+        
+        // Metadata
+        timestamp: new Date().toISOString(),
+        url: window.location.href,
+        userAgent: navigator.userAgent
+    };
+    
+    // Include course context
+    if (_config.includeContext !== false && _courseConfig) {
+        payload.course = {
+            title: _courseConfig.metadata?.title,
+            version: _courseConfig.metadata?.version,
+            id: _courseConfig.metadata?.id
+        };
+    }
+    
+    // Include current slide info if available
+    if (options.currentSlide) {
+        payload.currentSlide = options.currentSlide;
+    }
+    
+    // Include recent logs if requested and available
+    if (options.includeLogs && typeof getRecentLogs === 'function') {
+        payload.recentLogs = getRecentLogs();
+    }
+    
+    try {
+        const headers = { 'Content-Type': 'application/json' };
+        if (_config.apiKey) headers['Authorization'] = `Bearer ${_config.apiKey}`;
+
+        const response = await fetch(_config.endpoint, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(payload)
+        });
+        
+        if (response.ok) {
+            logger.debug('[ErrorReporter] User report submitted successfully');
+            return { success: true, message: 'Your report has been submitted. Thank you!' };
+        } else {
+            logger.warn('[ErrorReporter] Failed to submit user report:', response.status);
+            return { success: false, message: 'Failed to submit report. Please try again later.' };
+        }
+    } catch (e) {
+        logger.warn('[ErrorReporter] Network error submitting user report:', e.message);
+        return { success: false, message: 'Network error. Please check your connection and try again.' };
+    }
+}
+
+/**
+ * Initialize error reporting if configured
+ * 
+ * @param {Object} courseConfig - The course configuration object
+ */
+export function initErrorReporter(courseConfig) {
+    const config = courseConfig.environment?.errorReporting;
+    
+    // Store for user reports
+    _config = config;
+    _courseConfig = courseConfig;
+    
+    // Never send reports during local dev — the preview server and dev command
+    // inject VITE_COURSECODE_LOCAL into the Vite build env, which is auto-exposed
+    // to client code. Production builds via `coursecode build` don't set this.
+    if (import.meta.env.VITE_COURSECODE_LOCAL) {
+        logger.debug('[ErrorReporter] Disabled in local dev mode');
+        return;
+    }
+    
+    // Disabled if not configured or no endpoint
+    if (!config?.endpoint) {
+        logger.debug('[ErrorReporter] Not configured, skipping initialization');
+        return;
+    }
+    
+    logger.info('[ErrorReporter] Initialized with endpoint:', config.endpoint);
+    
+    // Subscribe to unified logger events
+    eventBus.on('log:error', (errorData) => {
+        if (_isReporting) return; // prevent re-entrancy from our own logger calls
+        enqueueError(errorData, config, courseConfig);
+    });
+    eventBus.on('log:warn', (errorData) => {
+        if (_isReporting) return; // prevent re-entrancy from our own logger calls
+        enqueueError(errorData, config, courseConfig);
+    });
+}

package/framework/js/utilities/hotspot-helper.js

@@ -0,0 +1,341 @@
+/**
+ * Hotspot Coordinate Helper Utility
+ * Development tool to help authors determine hotspot coordinates
+ *
+ * Usage:
+ * import { enableHotspotHelper } from '../../../framework/js/utilities/hotspot-helper.js';
+ *
+ * // In your slide render function:
+ * const img = document.querySelector('img');
+ * enableHotspotHelper(img);
+ *
+ * // Click on the image to see coordinates logged to console
+ */
+
+import { logger } from './logger.js';
+
+/**
+ * Enable coordinate helper on an image element
+ * Logs pixel and percentage coordinates on click
+ * @param {HTMLImageElement} imageElement - Image element to attach helper to
+ * @param {Object} options - Configuration options
+ * @param {boolean} options.showOverlay - Show visual overlay (default: true)
+ * @param {boolean} options.showPixels - Log pixel coordinates (default: true)
+ * @param {boolean} options.showPercent - Log percentage coordinates (default: true)
+ * @param {string} options.outputFormat - 'json' or 'code' (default: 'both')
+ */
+export function enableHotspotHelper(imageElement, options = {}) {
+  const {
+    showOverlay = true,
+    showPixels = true,
+    showPercent = true,
+    outputFormat = 'both'
+  } = options;
+
+  if (!imageElement) {
+    logger.error('[HotspotHelper] No image element provided');
+    return;
+  }
+
+  // Wait for image to load
+  const initialize = () => {
+    const container = imageElement.parentElement;
+    let overlay = null;
+
+    if (showOverlay) {
+      // Create visual overlay
+      overlay = document.createElement('div');
+      overlay.style.cssText = `
+        position: absolute;
+        top: 0;
+        left: 0;
+        width: 100%;
+        height: 100%;
+        pointer-events: none;
+        z-index: 9999;
+      `;
+      container.style.position = 'relative';
+      container.appendChild(overlay);
+    }
+
+    const markers = [];
+
+    imageElement.addEventListener('click', (e) => {
+      const rect = imageElement.getBoundingClientRect();
+      const naturalWidth = imageElement.naturalWidth || imageElement.width;
+      const naturalHeight = imageElement.naturalHeight || imageElement.height;
+
+      const clickX = e.clientX - rect.left;
+      const clickY = e.clientY - rect.top;
+
+      const pixelX = Math.round((clickX / rect.width) * naturalWidth);
+      const pixelY = Math.round((clickY / rect.height) * naturalHeight);
+
+      const percentX = ((clickX / rect.width) * 100).toFixed(2);
+      const percentY = ((clickY / rect.height) * 100).toFixed(2);
+
+      logger.debug('\n=== Hotspot Coordinate Helper ===');
+      logger.debug(`Image: ${naturalWidth}x${naturalHeight}px`);
+
+      if (showPixels) {
+        logger.debug('\nPixel coordinates:');
+        logger.debug(`  x: ${pixelX}, y: ${pixelY}`);
+      }
+
+      if (showPercent) {
+        logger.debug('\nPercentage coordinates:');
+        logger.debug(`  x: ${percentX}%, y: ${percentY}%`);
+      }
+
+      if (outputFormat === 'json' || outputFormat === 'both') {
+        logger.debug('\nJSON format (circle):');
+        logger.debug(JSON.stringify({
+          id: 'hotspot-1',
+          shape: 'circle',
+          position: { cx: pixelX, cy: pixelY, r: 25 },
+          correct: true,
+          label: 'Hotspot Label'
+        }, null, 2));
+
+        logger.debug('\nJSON format (rectangle):');
+        logger.debug(JSON.stringify({
+          id: 'hotspot-1',
+          shape: 'rectangle',
+          position: { x: pixelX, y: pixelY, width: 50, height: 40 },
+          correct: true,
+          label: 'Hotspot Label'
+        }, null, 2));
+      }
+
+      if (outputFormat === 'code' || outputFormat === 'both') {
+        logger.debug('\nCode snippet (circle):');
+        logger.debug(`{
+  id: 'hotspot-1',
+  shape: 'circle',
+  position: { cx: ${pixelX}, cy: ${pixelY}, r: 25 },
+  correct: true,
+  label: 'Hotspot Label'
+}`);
+
+        logger.debug('\nCode snippet (rectangle):');
+        logger.debug(`{
+  id: 'hotspot-1',
+  shape: 'rectangle',
+  position: { x: ${pixelX}, y: ${pixelY}, width: 50, height: 40 },
+  correct: true,
+  label: 'Hotspot Label'
+}`);
+      }
+
+      // Add visual marker
+      if (overlay) {
+        const marker = document.createElement('div');
+        marker.style.cssText = `
+          position: absolute;
+          left: ${clickX}px;
+          top: ${clickY}px;
+          width: 10px;
+          height: 10px;
+          background: rgba(255, 0, 0, 0.7);
+          border: 2px solid white;
+          border-radius: 50%;
+          transform: translate(-50%, -50%);
+          pointer-events: none;
+        `;
+
+        const label = document.createElement('div');
+        label.style.cssText = `
+          position: absolute;
+          left: ${clickX + 10}px;
+          top: ${clickY - 10}px;
+          background: rgba(0, 0, 0, 0.8);
+          color: white;
+          padding: 2px 6px;
+          font-size: 11px;
+          border-radius: 3px;
+          white-space: nowrap;
+          pointer-events: none;
+        `;
+        label.textContent = `${pixelX}, ${pixelY}`;
+
+        overlay.appendChild(marker);
+        overlay.appendChild(label);
+        markers.push({ marker, label });
+      }
+
+      logger.debug('=================================\n');
+    });
+
+    // Add clear button
+    if (showOverlay) {
+      const clearButton = document.createElement('button');
+      clearButton.textContent = 'Clear Markers';
+      clearButton.style.cssText = `
+        position: absolute;
+        top: 10px;
+        right: 10px;
+        z-index: 10000;
+        padding: 5px 10px;
+        background: rgba(255, 0, 0, 0.8);
+        color: white;
+        border: none;
+        border-radius: 4px;
+        cursor: pointer;
+        font-size: 12px;
+      `;
+      clearButton.addEventListener('click', () => {
+        markers.forEach(({ marker, label }) => {
+          marker.remove();
+          label.remove();
+        });
+        markers.length = 0;
+      });
+      container.appendChild(clearButton);
+    }
+
+    logger.debug('[HotspotHelper] Enabled on image. Click to see coordinates.');
+  };
+
+  if (imageElement.complete) {
+    initialize();
+  } else {
+    imageElement.addEventListener('load', initialize);
+  }
+}
+
+/**
+ * Create an interactive hotspot designer
+ * Shows a UI for drawing hotspots on an image
+ * @param {HTMLImageElement} imageElement - Image element
+ * @param {Function} onSave - Callback when hotspots are saved
+ */
+export function createHotspotDesigner(imageElement, onSave) {
+  if (!imageElement) {
+    logger.error('[HotspotDesigner] No image element provided');
+    return;
+  }
+
+  const container = imageElement.parentElement;
+  container.style.position = 'relative';
+
+  const hotspots = [];
+  let _currentShape = 'circle';
+  const _isDrawing = false;
+  const _startPoint = null;
+
+  // Create UI
+  const ui = document.createElement('div');
+  ui.className = 'absolute p-3';
+  ui.style.cssText = `
+    top: 10px;
+    left: 10px;
+    background: white;
+    padding: 10px;
+    border-radius: 4px;
+    box-shadow: 0 2px 10px rgba(0,0,0,0.2);
+    z-index: 10000;
+  `;
+
+  ui.innerHTML = `
+    <div class="mb-2 font-semibold">Hotspot Designer</div>
+    <div class="mb-2">
+      <label>
+        <input type="radio" name="shape" value="circle" checked> Circle
+      </label>
+      <label class="ml-2">
+        <input type="radio" name="shape" value="rectangle"> Rectangle
+      </label>
+    </div>
+    <div class="mb-2">
+      <label>
+        <input type="checkbox" id="correct-checkbox" checked> Correct Answer
+      </label>
+    </div>
+    <button id="save-hotspots" class="btn btn-success w-full" style="padding: 5px;">
+      Save Hotspots
+    </button>
+    <button id="clear-all" class="btn btn-reset w-full mt-2" style="padding: 5px;">
+      Clear All
+    </button>
+  `;
+
+  container.appendChild(ui);
+
+  // Shape selection
+  ui.querySelectorAll('input[name="shape"]').forEach(input => {
+    input.addEventListener('change', (e) => {
+      currentShape = e.target.value;
+    });
+  });
+
+  // Save button
+  ui.querySelector('#save-hotspots').addEventListener('click', () => {
+    if (onSave) {
+      onSave(hotspots);
+    }
+    logger.debug('Hotspots configuration:');
+    logger.debug(JSON.stringify(hotspots, null, 2));
+  });
+
+  // Clear button
+  ui.querySelector('#clear-all').addEventListener('click', () => {
+    hotspots.length = 0;
+    // Clear visual markers
+  });
+
+  logger.debug('[HotspotDesigner] Enabled. Click and drag to draw hotspots.');
+}
+
+/**
+ * Convert percentage-based config to pixel-based config
+ * @param {Object} config - Hotspot config with percentage values
+ * @param {number} imageWidth - Image width in pixels
+ * @param {number} imageHeight - Image height in pixels
+ * @returns {Object} Config with pixel values
+ */
+export function percentToPixels(config, imageWidth, imageHeight) {
+  const converted = { ...config };
+
+  if (config.position) {
+    const pos = { ...config.position };
+
+    Object.keys(pos).forEach(key => {
+      if (typeof pos[key] === 'string' && pos[key].endsWith('%')) {
+        const percent = parseFloat(pos[key]);
+        const dimension = key === 'cx' || key === 'x' || key === 'width' ? imageWidth : imageHeight;
+        pos[key] = Math.round((percent / 100) * dimension);
+      }
+    });
+
+    converted.position = pos;
+  }
+
+  return converted;
+}
+
+/**
+ * Convert pixel-based config to percentage-based config
+ * @param {Object} config - Hotspot config with pixel values
+ * @param {number} imageWidth - Image width in pixels
+ * @param {number} imageHeight - Image height in pixels
+ * @returns {Object} Config with percentage values
+ */
+export function pixelsToPercent(config, imageWidth, imageHeight) {
+  const converted = { ...config };
+
+  if (config.position) {
+    const pos = { ...config.position };
+
+    Object.keys(pos).forEach(key => {
+      if (typeof pos[key] === 'number') {
+        const dimension = key === 'cx' || key === 'x' || key === 'width' ? imageWidth : imageHeight;
+        const percent = ((pos[key] / dimension) * 100).toFixed(2);
+        pos[key] = `${percent}%`;
+      }
+    });
+
+    converted.position = pos;
+  }
+
+  return converted;
+}