coursecode 0.1.0

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

@@ -0,0 +1,88 @@
+import interactionManager from './interaction-manager.js';
+import { logger } from '../utilities/logger.js';
+import stateManager from '../state/index.js';
+import { generateScormTimestamp } from '../validation/scorm-validators.js';
+
+/**
+ * @typedef {object} Comment
+ * @property {string} text - The content of the comment.
+ * @property {string} location - The slide or location where the comment was made.
+ * @property {string} timestamp - The ISO 8601 timestamp of when the comment was created.
+ */
+
+const DOMAIN_KEY = 'comments';
+
+class CommentManager {
+    /**
+     * @type {Comment[]}
+     */
+    #comments;
+
+    constructor() {
+        this.#comments = [];
+    }
+
+    /**
+     * Initializes the manager by hydrating comments from domain state.
+     * This must be called after the StateManager is initialized.
+     */
+    initialize() {
+        this.#comments = stateManager.getDomainState(DOMAIN_KEY) || [];
+        logger.debug('CommentManager initialized');
+    }
+
+    /**
+     * Adds a new comment and persists it to the LMS.
+     * @param {string} text - The content of the comment.
+     * @param {string} [location=''] - The slide ID or location identifier.
+     * @throws {Error} If text is empty or not a valid string
+     */
+    addComment(text, location = '') {
+        if (!text || typeof text !== 'string' || text.trim() === '') {
+            throw new Error('CommentManager: Comment text cannot be empty.');
+        }
+
+        const newComment = {
+            text,
+            location,
+            timestamp: generateScormTimestamp(),
+        };
+
+        // Update in-memory state
+        this.#comments.push(newComment);
+
+        // Persist via domain state (stored in suspend_data)
+        stateManager.setDomainState(DOMAIN_KEY, this.#comments);
+
+        logger.debug('Comment added and persisted:', newComment);
+    }
+
+    /**
+     * Adds a course rating as a likert interaction.
+     * @param {number | string} rating - The rating value provided by the user.
+     */
+    addRating(rating) {
+        if (rating === null || rating === undefined) {
+            return;
+        }
+
+        interactionManager.addLikertInteraction({
+            id: 'course-rating',
+            response: String(rating),
+            description: 'Overall course satisfaction rating on a 5-star scale.'
+        });
+
+        logger.debug('Rating added and persisted to LMS:', rating);
+    }
+
+    /**
+     * Retrieves all comments from the in-memory store.
+     * @returns {Comment[]} An array of all comments.
+     */
+    getComments() {
+        return [...this.#comments];
+    }
+}
+
+const commentManager = new CommentManager();
+export default commentManager;

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

@@ -0,0 +1,86 @@
+/**
+ * @file flag-manager.js
+ * @description Manages global flags for the course. It provides a simple API
+ * for setting and retrieving boolean flags, persisting the entire flags object
+ * as a single domain in the StateManager.
+ */
+
+import stateManager from '../state/index.js';
+import { logger } from '../utilities/logger.js';
+import { eventBus } from '../core/event-bus.js';
+import { deepClone } from '../utilities/utilities.js';
+
+class FlagManager {
+    constructor() {
+        this.flags = {};
+        this.isInitialized = false;
+        this.DOMAIN_KEY = 'flags';
+        this.SOURCE = 'flag-manager';
+    }
+
+    /**
+     * Initializes the manager by loading flags from the StateManager.
+     * @throws {Error} If already initialized
+     */
+    initialize() {
+        if (this.isInitialized) {
+            throw new Error('FlagManager: Already initialized. Do not call initialize() more than once.');
+        }
+        const persistedFlags = stateManager.getDomainState(this.DOMAIN_KEY);
+        if (persistedFlags && typeof persistedFlags === 'object') {
+            this.flags = persistedFlags;
+        }
+        this.isInitialized = true;
+        logger.debug('FlagManager initialized.', this.flags);
+    }
+
+    /**
+     * Retrieves all flags.
+     * @returns {object} A deep-cloned object of all flags.
+     */
+    getAllFlags() {
+        return deepClone(this.flags);
+    }
+
+    /**
+     * Retrieves a single flag by its key.
+     * @param {string} key - The key for the flag.
+     * @returns {any} The value of the flag, or undefined if not found.
+     */
+    getFlag(key) {
+        const val = this.flags[key];
+        return (val && typeof val === 'object') ? deepClone(val) : val;
+    }
+
+    /**
+     * Sets a flag's value and persists the change.
+     * @param {string} key - The key for the flag.
+     * @param {any} value - The value to set for the flag.
+     * @throws {Error} If key is not a non-empty string
+     */
+    setFlag(key, value) {
+        if (typeof key !== 'string' || key.trim() === '') {
+            throw new Error('FlagManager: setFlag requires a non-empty string key.');
+        }
+
+        this.flags[key] = value;
+
+        stateManager.setDomainState(this.DOMAIN_KEY, this.flags, { source: this.SOURCE });
+        eventBus.emit('flag:updated', { key, value });
+    }
+
+    /**
+     * Removes a flag and persists the change.
+     * @param {string} key - The key for the flag to remove.
+     */
+    removeFlag(key) {
+        if (this.flags.hasOwnProperty(key)) {
+            delete this.flags[key];
+            stateManager.setDomainState(this.DOMAIN_KEY, this.flags, { source: this.SOURCE });
+            eventBus.emit('flag:removed', { key });
+        }
+    }
+}
+
+const instance = new FlagManager();
+export default instance;

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

@@ -0,0 +1,254 @@
+/**
+ * @file interaction-manager.js
+ * @description Manages student interactions for SCORM persistence.
+ * This is the single source of truth for all interaction data and persists
+ * its state through the StateManager.
+ */
+
+import { logger } from '../utilities/logger.js';
+
+import { deepClone, generateId } from '../utilities/utilities.js';
+import stateManager from '../state/index.js';
+import { eventBus } from '../core/event-bus.js';
+import {
+    SCORM_INTERACTION_TYPES as _SCORM_INTERACTION_TYPES,
+    SCORM_INTERACTION_RESULTS as _SCORM_INTERACTION_RESULTS,
+    isValidISO8601Timestamp,
+    isValidISO8601Duration,
+    validateInteractionType,
+    validateInteractionResult,
+    validateNumeric,
+    validateStringArray,
+    validateRequiredFields,
+    formatValidationError,
+    generateScormTimestamp
+} from '../validation/scorm-validators.js';
+
+/**
+ * @typedef {Object} InteractionData
+ * @property {string} [id] - Unique identifier (auto-generated if not provided)
+ * @property {string} type - SCORM interaction type
+ * @property {string} [learner_response] - The learner's response
+ * @property {string} [result] - Result of the interaction
+ * @property {string} [description] - Description of the interaction
+ * @property {string} [timestamp] - ISO 8601 timestamp
+ * @property {number} [weighting] - Weight of the interaction
+ * @property {string} [latency] - ISO 8601 duration format
+ * @property {string[]} [correct_responses] - Array of correct response patterns
+ * @property {string[]} [objectives] - Array of linked objective IDs
+ */
+
+class InteractionManager {
+    constructor() {
+        this.interactions = [];
+        this.isInitialized = false;
+        this.DOMAIN_KEY = 'interactions';
+        this.SOURCE = 'interaction-manager';
+    }
+
+    /**
+     * Initializes the manager by loading state from the StateManager.
+     * @throws {Error} If already initialized
+     */
+    initialize() {
+        if (this.isInitialized) {
+            throw new Error('InteractionManager: Already initialized. Do not call initialize() more than once.');
+        }
+
+        // Load interactions via stateManager domain API
+        // stateManager transparently routes to cmi.interactions.n.*
+        this.interactions = stateManager.getDomainState(this.DOMAIN_KEY) || [];
+
+        this.isInitialized = true;
+        logger.debug('InteractionManager initialized.', this.interactions);
+    }
+
+    /**
+     * Retrieves all interactions.
+     * @returns {Array<object>} A deep-cloned array of all interaction objects.
+     */
+    getAllInteractions() {
+        return deepClone(this.interactions);
+    }
+
+    /**
+     * Retrieves a single interaction by its ID.
+     * @param {string} id - The unique identifier for the interaction.
+     * @returns {object|null} A deep-cloned interaction object or null if not found.
+     */
+    getInteraction(id) {
+        const interaction = this.interactions.find(i => i.id === id);
+        return interaction ? deepClone(interaction) : null;
+    }
+
+    /**
+     * Validates interaction data against SCORM 2004 4th Edition specification.
+     * @private
+     * @param {InteractionData} data - The interaction data to validate
+     * @throws {Error} If validation fails with detailed error messages
+     */
+    _validateInteractionData(data) {
+        if (!data || typeof data !== 'object') {
+            throw new Error('[InteractionManager] Interaction data must be a non-null object');
+        }
+
+        const errors = [];
+
+        // Validate required field: type
+        const requiredCheck = validateRequiredFields(data, ['type']);
+        if (!requiredCheck.valid) {
+            errors.push(...requiredCheck.errors);
+        } else {
+            // Only validate type value if field is present
+            const typeCheck = validateInteractionType(data.type);
+            if (!typeCheck.valid) {
+                errors.push(typeCheck.error);
+            }
+        }
+
+        // Validate result if provided
+        if (data.result) {
+            const resultCheck = validateInteractionResult(data.result);
+            if (!resultCheck.valid) {
+                errors.push(resultCheck.error);
+            }
+        }
+
+        // Validate timestamp format if provided
+        if (data.timestamp && !isValidISO8601Timestamp(data.timestamp)) {
+            errors.push(`Invalid timestamp "${data.timestamp}". Must be ISO 8601 format`);
+        }
+
+        // Validate weighting if provided
+        if (data.weighting !== undefined && data.weighting !== null) {
+            const weightCheck = validateNumeric(data.weighting, 'weighting');
+            if (!weightCheck.valid) {
+                errors.push(weightCheck.error);
+            }
+        }
+
+        // Validate latency format if provided (ISO 8601 duration)
+        if (data.latency && !isValidISO8601Duration(data.latency)) {
+            errors.push(`Invalid latency "${data.latency}". Must be ISO 8601 duration format (e.g., "PT1H30M")`);
+        }
+
+        // Validate correct_responses if provided
+        if (data.correct_responses !== undefined && !Array.isArray(data.correct_responses)) {
+            errors.push('Field "correct_responses" must be an array');
+        }
+
+        // Validate objectives if provided
+        if (data.objectives !== undefined) {
+            const objCheck = validateStringArray(data.objectives, 'objectives');
+            if (!objCheck.valid) {
+                errors.push(objCheck.error);
+            }
+        }
+
+        if (errors.length > 0) {
+            const context = data.id ? `interaction "${data.id}"` : 'interaction';
+            const errorMsg = '[InteractionManager] ' + formatValidationError(errors, context);
+            throw new Error(errorMsg);
+        }
+    }
+
+    /**
+     * Records a new interaction.
+     * Uses stateManager's domain API with append-only semantics.
+     * stateManager handles all CMI routing transparently.
+     * 
+     * @param {InteractionData} interactionData - The interaction data conforming to SCORM CMI data model
+     * @returns {object} The recorded interaction object, including generated ID and timestamp
+     * @throws {Error} If validation fails or state persistence fails
+     */
+    record(interactionData) {
+        // Validate input - this will throw if validation fails
+        this._validateInteractionData(interactionData);
+
+        const newInteraction = {
+            id: interactionData.id || generateId('interaction'),
+            type: interactionData.type,
+            learner_response: interactionData.learner_response || '',
+            result: interactionData.result || 'neutral',
+            description: interactionData.description || '',
+            timestamp: interactionData.timestamp || generateScormTimestamp(),
+            weighting: interactionData.weighting,
+            latency: interactionData.latency,
+            correct_responses: interactionData.correct_responses,
+            objectives: interactionData.objectives
+        };
+
+        // Persist via stateManager domain API (append-only semantics)
+        // stateManager transparently routes to cmi.interactions.n.*
+        try {
+            const result = stateManager.setDomainState(this.DOMAIN_KEY, newInteraction);
+            // Update in-memory array with the result (includes _index from stateManager)
+            this.interactions.push(result || newInteraction);
+        } catch (error) {
+            const wrappedError = new Error(`[InteractionManager] Failed to record interaction "${newInteraction.id}": ${error.message}`);
+            this._emitError('record', wrappedError, { interactionId: newInteraction.id });
+            throw wrappedError;
+        }
+
+        eventBus.emit('interaction:recorded', newInteraction);
+
+        return deepClone(newInteraction);
+    }
+
+    /**
+     * Adds a likert interaction to the LMS.
+     * Likert interactions are used for ratings and feedback (1-5 scales, etc).
+     * 
+     * This method now uses record() internally to ensure consistent validation,
+     * error handling, and state management.
+     * 
+     * @param {object} interaction - The interaction data.
+     * @param {string} interaction.id - A unique identifier for the interaction.
+     * @param {string} interaction.response - The learner's response.
+     * @param {string} interaction.description - A description of the interaction.
+     * @returns {object} The recorded interaction object
+     * @throws {Error} If InteractionManager is not initialized
+     * @throws {Error} If interaction data is invalid
+     * @throws {Error} If SCORM sync or state persistence fails
+     */
+    addLikertInteraction({ id, response, description }) {
+        if (!this.isInitialized) {
+            const error = new Error('[InteractionManager] Not initialized. Call initialize() first.');
+            this._emitError('addLikertInteraction', error, { interactionId: id });
+            throw error;
+        }
+        if (!id || typeof id !== 'string') {
+            const error = new Error('[InteractionManager] likert interaction id is required and must be a string');
+            this._emitError('addLikertInteraction', error, { interactionId: id });
+            throw error;
+        }
+        if (response === undefined || response === null || String(response).trim() === '') {
+            const error = new Error('[InteractionManager] likert interaction response is required');
+            this._emitError('addLikertInteraction', error, { interactionId: id });
+            throw error;
+        }
+
+        // Use record() to ensure consistent validation and state management
+        return this.record({
+            id: id,
+            type: 'likert',
+            learner_response: String(response),
+            description: description || '',
+            result: 'neutral'  // Likert doesn't have right/wrong answers
+        });
+    }
+
+    /**
+     * Logs a standardized error for interaction operations.
+     * @private
+     * @param {string} operation - The operation that failed
+     * @param {Error} error - The error object
+     * @param {object} context - Additional context about the error
+     */
+    _emitError(operation, error, context) {
+        logger.error(error.message, { domain: 'interaction', operation, stack: error.stack, ...context });
+    }
+}
+
+const instance = new InteractionManager();
+export default instance;

package/framework/js/managers/interaction-registry.js

@@ -0,0 +1,96 @@
+/**
+ * @file interaction-registry.js
+ * @description Runtime registry for currently rendered interaction component instances.
+ * Separate from InteractionManager which handles SCORM persistence.
+ * 
+ * This registry tracks interactions on the CURRENT SLIDE ONLY and is cleared on navigation.
+ * It provides a live reference to interaction instances for:
+ * - EngagementManager: counting interactions for completion requirements
+ * - Automation API: programmatic testing and manipulation
+ * 
+ * NOTE: This registry is NOT used by runtime-linter. The linter performs static analysis
+ * by rendering slides to detached DOM and querying for [data-interaction-id] elements.
+ */
+
+import { eventBus } from '../core/event-bus.js';
+import { logger } from '../utilities/logger.js';
+
+class InteractionRegistry {
+    constructor() {
+        this.registry = new Map();
+        this.isReady = false;
+    }
+
+    /**
+     * Registers an interaction component instance when it is rendered.
+     * @param {object} config - The interaction configuration object
+     * @param {object} questionObj - The live interaction instance with methods like evaluate()
+     * @throws {Error} If configuration is invalid or duplicate ID detected
+     */
+    register(config, questionObj) {
+        if (!config || !config.id) {
+            const error = new Error('[InteractionRegistry] Cannot register interaction: configuration or ID is missing.');
+            eventBus.emit('interaction:registry:error', {
+                domain: 'interaction-registry',
+                operation: 'register',
+                message: error.message,
+                stack: error.stack,
+                context: { config }
+            });
+            throw error;
+        }
+
+        if (this.registry.has(config.id)) {
+            const error = new Error(`[InteractionRegistry] Interaction with ID "${config.id}" is already registered. Duplicate interaction IDs are not allowed. Each interaction must have a unique ID.`);
+            eventBus.emit('interaction:registry:error', {
+                domain: 'interaction-registry',
+                operation: 'register',
+                message: error.message,
+                stack: error.stack,
+                context: { interactionId: config.id }
+            });
+            throw error;
+        }
+
+        const registration = {
+            id: config.id,
+            type: config.type,
+            description: config.prompt,
+            config: config,
+            instance: questionObj,
+        };
+
+        this.registry.set(config.id, registration);
+        eventBus.emit('interaction:registered', registration);
+    }
+
+    /**
+     * Retrieves all registered interactions for the current slide.
+     * @returns {Array<object>} Array of registered interaction objects with their instances and configs
+     */
+    getAll() {
+        return Array.from(this.registry.values());
+    }
+
+    /**
+     * Clears the registry. Should be called before rendering a new slide.
+     */
+    clear() {
+        this.registry.clear();
+        this.isReady = false;
+        logger.debug('[InteractionRegistry] Registry cleared.');
+    }
+
+    /**
+     * Marks the registry as ready after all interactions have been registered.
+     * Emits an event that other managers can listen to.
+     */
+    setReady() {
+        this.isReady = true;
+        eventBus.emit('interaction:registry:ready', this.getAll());
+        logger.debug(`[InteractionRegistry] Registry ready. ${this.registry.size} interactions registered.`);
+    }
+}
+
+const instance = new InteractionRegistry();
+export default instance;