coursecode 0.1.0

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

@@ -0,0 +1,77 @@
+/**
+ * @file driver-factory.js
+ * @description Factory for creating LMS drivers based on format configuration.
+ * 
+ * All drivers are included as lazy chunks in the universal build.
+ * Only the driver matching the runtime format is loaded (via dynamic import).
+ * This enables a single build to serve any LMS format — the format is
+ * determined at runtime from a <meta name="lms-format"> tag in index.html.
+ */
+
+import { validateDriverInterface } from './driver-interface.js';
+
+// Cached driver instances (drivers are singletons)
+let cachedDriver = null;
+let cachedFormat = null;
+
+/**
+ * Creates the appropriate LMS driver based on format.
+ * All drivers exist as lazy chunks; only the matching one is loaded at runtime.
+ * @param {string} format - 'cmi5' | 'cmi5-remote' | 'scorm2004' | 'scorm1.2' | 'scorm1.2-proxy' | 'scorm2004-proxy' | 'lti'
+ * @returns {Promise<LMSDriver>} The driver instance
+ */
+export async function createDriver(format = 'cmi5') {
+    // Return cached driver if same format
+    if (cachedDriver && cachedFormat === format) {
+        return cachedDriver;
+    }
+
+    let driver;
+
+    switch (format) {
+        case 'scorm2004': {
+            const { Scorm2004Driver } = await import('./scorm-2004-driver.js');
+            driver = new Scorm2004Driver();
+            break;
+        }
+
+        case 'scorm1.2': {
+            const { Scorm12Driver } = await import('./scorm-12-driver.js');
+            driver = new Scorm12Driver();
+            break;
+        }
+
+        case 'scorm1.2-proxy':
+        case 'scorm2004-proxy': {
+            const { ProxyDriver } = await import('./proxy-driver.js');
+            // Extract base format (e.g., 'scorm1.2-proxy' -> 'scorm1.2')
+            const baseFormat = format.replace('-proxy', '');
+            driver = new ProxyDriver(baseFormat);
+            break;
+        }
+
+        case 'lti': {
+            const { LtiDriver } = await import('./lti-driver.js');
+            driver = new LtiDriver();
+            break;
+        }
+
+        case 'cmi5':
+        case 'cmi5-remote':
+        default: {
+            const { Cmi5Driver } = await import('./cmi5-driver.js');
+            driver = new Cmi5Driver();
+            break;
+        }
+    }
+
+    // Validate interface in development
+    if (import.meta.env.DEV) {
+        validateDriverInterface(driver);
+    }
+
+    cachedDriver = driver;
+    cachedFormat = format;
+
+    return driver;
+}

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

@@ -0,0 +1,110 @@
+/**
+ * @file driver-interface.js
+ * @description Defines the semantic interface contract for LMS drivers.
+ * All drivers (SCORM 2004, SCORM 1.2, cmi5, LTI, Proxy) must implement this interface.
+ *
+ * The interface uses semantic methods instead of CMI keys. Each driver translates
+ * to its native protocol (CMI for SCORM, xAPI for cmi5, HTTP for LTI, postMessage for Proxy).
+ */
+
+/**
+ * @typedef {Object} DriverCapabilities
+ * @property {boolean} supportsObjectives - Can store learning objectives
+ * @property {boolean} supportsInteractions - Can store interaction records
+ * @property {boolean} supportsComments - Can store learner comments
+ * @property {boolean} supportsEmergencySave - Has sendBeacon fallback for page unload
+ * @property {number} maxSuspendDataBytes - Max suspend_data size (0 = unlimited)
+ * @property {boolean} asyncCommit - Whether commit() is async (HTTP-based)
+ */
+
+/**
+ * @typedef {Object} LMSDriver
+ *
+ * Lifecycle:
+ * @property {function(): Promise<boolean>} initialize - Initialize connection
+ * @property {function(): Promise<boolean>} terminate - Terminate connection
+ * @property {function(): Promise<boolean>} commit - Commit buffered writes
+ * @property {function(): DriverCapabilities} getCapabilities - Declare format capabilities
+ * @property {function(): 'scorm2004'|'scorm1.2'|'cmi5'|'lti'} getFormat - Get format identifier
+ * @property {function(): boolean} isConnected - Check if driver is connected
+ * @property {function(): boolean} isTerminated - Check if driver is terminated
+ *
+ * State persistence (suspend_data blob):
+ * @property {function(): object|null} getSuspendData - Get parsed suspend_data object
+ * @property {function(object): boolean} setSuspendData - Set suspend_data from object
+ *
+ * Semantic reads:
+ * @property {function(): string} getEntryMode - Returns 'ab-initio' | 'resume' | ''
+ * @property {function(): string} getBookmark - Returns current slide location or ''
+ * @property {function(): string} getCompletion - Returns 'completed' | 'incomplete' | 'unknown'
+ * @property {function(): string} getSuccess - Returns 'passed' | 'failed' | 'unknown'
+ * @property {function(): {scaled: number, raw: number, min: number, max: number}|null} getScore - Returns last reported score or null
+ * @property {function(): {id: string, name: string}} getLearnerInfo - Returns learner identity
+ *
+ * Semantic writes:
+ * @property {function(string): void} setBookmark - Persist slide position
+ * @property {function({raw: number, scaled: number, min: number, max: number}): void} reportScore - Report score
+ * @property {function(string): void} reportCompletion - 'completed' | 'incomplete'
+ * @property {function(string): void} reportSuccess - 'passed' | 'failed' | 'unknown'
+ * @property {function(number): void} reportProgress - 0.0 to 1.0
+ * @property {function(string): void} reportSessionTime - ISO 8601 duration string
+ * @property {function(Object): void} reportObjective - Report objective status
+ * @property {function(Object): void} reportInteraction - Report interaction data
+ * @property {function(string): void} setExitMode - 'suspend' | 'normal'
+ *
+ * Optional:
+ * @property {function(): void} [ping] - Keep-alive ping
+ * @property {function(): void} [emergencySave] - Synchronous emergency save using sendBeacon
+ *
+ * Optional xAPI (cmi5 only):
+ * @property {function(Object): Promise<void>} [sendObjectiveStatement] - Send objective xAPI statement
+ * @property {function(Object): Promise<void>} [sendInteractionStatement] - Send interaction xAPI statement
+ * @property {function(Object): Promise<void>} [sendAssessmentStatement] - Send assessment xAPI statement
+ * @property {function(Object): Promise<void>} [sendSlideStatement] - Send slide experienced xAPI statement
+ * @property {function(): Object|null} [getLaunchData] - Get cmi5 launch data
+ */
+
+
+/**
+ * Creates a driver interface validator (development-time check).
+ * @param {object} driver - Driver instance to validate
+ * @throws {Error} If driver doesn't implement required methods
+ */
+export function validateDriverInterface(driver) {
+    const requiredMethods = [
+        // Lifecycle
+        'initialize',
+        'terminate',
+        'commit',
+        'getCapabilities',
+        'getFormat',
+        'isConnected',
+        'isTerminated',
+        // State persistence
+        'getSuspendData',
+        'setSuspendData',
+        // Semantic reads
+        'getEntryMode',
+        'getBookmark',
+        'getCompletion',
+        'getSuccess',
+        'getScore',
+        'getLearnerInfo',
+        // Semantic writes
+        'setBookmark',
+        'reportScore',
+        'reportCompletion',
+        'reportSuccess',
+        'reportProgress',
+        'reportSessionTime',
+        'reportObjective',
+        'reportInteraction',
+        'setExitMode'
+    ];
+
+    for (const method of requiredMethods) {
+        if (typeof driver[method] !== 'function') {
+            throw new Error(`LMS Driver missing required method: ${method}`);
+        }
+    }
+}

package/framework/js/drivers/http-driver-base.js

@@ -0,0 +1,241 @@
+/**
+ * @file http-driver-base.js
+ * @description Base class for HTTP-based LMS drivers (cmi5, LTI).
+ * Consolidates shared mock state management, suspend data caching,
+ * semantic reads/writes, and commit logic.
+ *
+ * Subclasses must implement:
+ * - getFormat()
+ * - getCapabilities()
+ * - initialize()
+ * - terminate()
+ * - emergencySave()
+ * - getLearnerInfo()
+ * - getLaunchData()
+ * - _loadMockState()
+ * - _saveMockState()
+ * - _persistState()
+ */
+
+import { eventBus } from '../core/event-bus.js';
+import { logger } from '../utilities/logger.js';
+
+export class HttpDriverBase {
+    constructor() {
+        this._isConnected = false;
+        this._isTerminated = false;
+        this._mock = false;
+        this._mockState = {};
+        this._devApi = null;
+
+        // Local caches for synchronous access (pre-fetched on initialize)
+        this._suspendDataCache = null;
+        this._bookmarkCache = null;
+        this._suspendDataDirty = false;
+        this._bookmarkDirty = false;
+
+        // Cached status values
+        this._completionStatus = 'unknown';
+        this._successStatus = 'unknown';
+        this._score = null;
+    }
+
+    // =========================================================================
+    // Interface: Lifecycle Queries
+    // =========================================================================
+
+    isConnected() {
+        return this._isConnected;
+    }
+
+    isTerminated() {
+        return this._isTerminated;
+    }
+
+    /**
+     * Keep-alive ping — no-op for HTTP-based drivers (stateless).
+     */
+    ping() {
+        // HTTP-based drivers use stateless requests — no session keep-alive needed
+    }
+
+    // =========================================================================
+    // Interface: Commit
+    // =========================================================================
+
+    async commit() {
+        this._ensureInitialized();
+
+        if (this._isTerminated) {
+            return false;
+        }
+
+        if (this._mock) {
+            this._saveMockState();
+            return true;
+        }
+
+        await this._persistState();
+        return true;
+    }
+
+    // =========================================================================
+    // Interface: Semantic Reads
+    // =========================================================================
+
+    getEntryMode() {
+        return this._bookmarkCache ? 'resume' : 'ab-initio';
+    }
+
+    getBookmark() {
+        return this._bookmarkCache || '';
+    }
+
+    getCompletion() {
+        return this._completionStatus;
+    }
+
+    getSuccess() {
+        return this._successStatus;
+    }
+
+    getScore() {
+        if (this._score === null) return null;
+        const raw = Math.round(this._score * 100 * 100) / 100;
+        return { scaled: this._score, raw, min: 0, max: 100 };
+    }
+
+    // =========================================================================
+    // Interface: Semantic Writes
+    // =========================================================================
+
+    setBookmark(location) {
+        this._bookmarkCache = location;
+        this._bookmarkDirty = true;
+        if (this._mock) this._saveMockState();
+    }
+
+    reportScore({ raw, scaled, min: _min, max: _max }) {
+        if (scaled !== undefined) {
+            this._score = scaled;
+        } else if (raw !== undefined) {
+            this._score = raw / 100;
+        }
+    }
+
+    reportCompletion(status) {
+        this._completionStatus = status;
+    }
+
+    reportSuccess(status) {
+        this._successStatus = status;
+    }
+
+    reportProgress(_measure) {
+        // HTTP-based drivers don't have a native progress_measure
+    }
+
+    reportSessionTime(_duration) {
+        // Session time handled by protocol-specific mechanisms
+    }
+
+    reportObjective(_objective) {
+        // Objectives stored via suspend_data only
+    }
+
+    reportInteraction(_interaction) {
+        // Interactions stored via suspend_data only
+    }
+
+    setExitMode(_mode) {
+        // HTTP-based drivers don't have an exit mode concept
+    }
+
+    // =========================================================================
+    // Interface: Suspend Data
+    // =========================================================================
+
+    getSuspendData() {
+        this._ensureInitialized();
+
+        if (this._mock) {
+            return this._mockState.suspendData || null;
+        }
+
+        return this._suspendDataCache;
+    }
+
+    setSuspendData(data) {
+        this._ensureInitialized();
+
+        if (data === undefined || data === null) {
+            throw new Error('Cannot set suspend_data: data is null or undefined');
+        }
+
+        if (this._mock) {
+            this._mockState.suspendData = data;
+            this._saveMockState();
+            return true;
+        }
+
+        this._suspendDataCache = data;
+        this._suspendDataDirty = true;
+
+        const sizeKB = (JSON.stringify(data).length / 1024).toFixed(2);
+        logger.debug(`[${this.constructor.name}] suspend_data cached: ${sizeKB}KB`);
+
+        eventBus.emit('suspend-data:size', {
+            bytes: JSON.stringify(data).length,
+            kilobytes: parseFloat(sizeKB),
+            format: this.getFormat()
+        });
+
+        return true;
+    }
+
+    // =========================================================================
+    // Shared Mock Helpers
+    // =========================================================================
+
+    /**
+     * Shared mock terminate flow — logs completion/success/failure/terminated
+     * statements and calls devApi.terminate(). Returns true.
+     */
+    _terminateMock() {
+        this._saveMockState();
+        if (this._completionStatus === 'completed') {
+            this._logMockStatement('completed', { verb: 'completed' });
+        }
+        if (this._successStatus === 'passed') {
+            this._logMockStatement('passed', { verb: 'passed', score: this._score });
+        } else if (this._successStatus === 'failed') {
+            this._logMockStatement('failed', { verb: 'failed', score: this._score });
+        }
+        this._logMockStatement('terminated', { verb: 'terminated' });
+        if (this._devApi) {
+            this._devApi.terminate();
+        }
+        this._isTerminated = true;
+        logger.debug(`[${this.constructor.name}] Mock session terminated`);
+        return true;
+    }
+
+    _logMockStatement(type, data) {
+        const statement = { type, data, timestamp: new Date().toISOString() };
+        logger.debug(`[${this.constructor.name}] Mock ${type} statement:`, statement);
+        eventBus.emit('xapi:statement', statement);
+        if (this._devApi && typeof this._devApi.recordStatement === 'function') {
+            this._devApi.recordStatement(statement);
+        }
+    }
+
+    // =========================================================================
+    // Internal Utilities
+    // =========================================================================
+
+    _ensureInitialized() {
+        if (!this._isConnected) {
+            throw new Error(`${this.getFormat()} not initialized. Call initialize() first.`);
+        }
+    }
+}