coursecode 0.1.0

package/framework/js/automation/api-interactions.js

@@ -0,0 +1,167 @@
+/**
+ * @file api-interactions.js
+ * Interaction discovery, state access, mutation, and evaluation methods
+ * for the CourseCodeAutomation API.
+ */
+
+import interactionRegistry from '../managers/interaction-registry.js';
+import { courseConfig } from '../../../course/course-config.js';
+import { recordInteractionResult } from '../components/interactions/interaction-base.js';
+import { logger } from '../utilities/logger.js';
+
+/**
+ * Creates interaction API methods bound to the shared logTrace function.
+ * @param {Function} logTrace - Shared trace logger
+ * @returns {Object} Interaction API methods
+ */
+export function createInteractionMethods(logTrace) {
+    return {
+        listInteractions() {
+            const interactions = interactionRegistry.getAll();
+            const simplifiedList = interactions.map(i => ({
+                id: i.id,
+                type: i.type,
+                description: i.description
+            }));
+            logTrace('listInteractions', { count: simplifiedList.length });
+            return simplifiedList;
+        },
+
+        getInteractionMetadata(interactionId) {
+            const entry = interactionRegistry.getAll().find(i => i.id === interactionId);
+            if (!entry) {
+                throw new Error(`CourseCodeAutomation: Interaction "${interactionId}" not found on the current slide`);
+            }
+            logTrace('getInteractionMetadata', { interactionId });
+            return {
+                id: entry.id,
+                type: entry.type,
+                description: entry.description
+            };
+        },
+
+        getResponse(interactionId) {
+            const entry = interactionRegistry.getAll().find(i => i.id === interactionId);
+            if (!entry || !entry.instance) {
+                throw new Error(`CourseCodeAutomation: Interaction "${interactionId}" not found or has no instance`);
+            }
+
+            if (typeof entry.instance.getResponse !== 'function') {
+                throw new Error(`CourseCodeAutomation: Interaction "${interactionId}" does not support getResponse`);
+            }
+
+            const response = entry.instance.getResponse();
+            logTrace('getResponse', { interactionId, response });
+            return response;
+        },
+
+        getCorrectResponse(interactionId) {
+            if (!courseConfig.environment?.automation?.exposeCorrectAnswers) {
+                throw new Error('CourseCodeAutomation: getCorrectResponse requires automation.exposeCorrectAnswers=true in course config');
+            }
+
+            const entry = interactionRegistry.getAll().find(i => i.id === interactionId);
+            if (!entry || !entry.instance) {
+                throw new Error(`CourseCodeAutomation: Interaction "${interactionId}" not found or has no instance`);
+            }
+
+            if (typeof entry.instance.getCorrectAnswer !== 'function') {
+                throw new Error(`CourseCodeAutomation: Interaction "${interactionId}" does not support getCorrectAnswer`);
+            }
+
+            const correctAnswer = entry.instance.getCorrectAnswer();
+            logTrace('getCorrectResponse', { interactionId });
+            return correctAnswer;
+        },
+
+        setResponse(interactionId, response) {
+            const entry = interactionRegistry.getAll().find(i => i.id === interactionId);
+            if (!entry || !entry.instance) {
+                throw new Error(`CourseCodeAutomation: Interaction "${interactionId}" not found or has no instance`);
+            }
+
+            if (typeof entry.instance.setResponse !== 'function') {
+                throw new Error(`CourseCodeAutomation: Interaction "${interactionId}" does not support setResponse`);
+            }
+
+            try {
+                entry.instance.setResponse(response);
+                logTrace('setResponse', { interactionId, response });
+            } catch (error) {
+                logTrace('setResponse:error', { interactionId, response, error: error.message });
+                throw new Error(`CourseCodeAutomation: Failed to set response for "${interactionId}": ${error.message}`);
+            }
+        },
+
+        checkAnswer(interactionId) {
+            const entry = interactionRegistry.getAll().find(i => i.id === interactionId);
+            if (!entry || !entry.instance) {
+                throw new Error(`CourseCodeAutomation: Interaction "${interactionId}" not found or has no instance`);
+            }
+
+            if (typeof entry.instance.checkAnswer !== 'function') {
+                throw new Error(`CourseCodeAutomation: Interaction "${interactionId}" does not support checkAnswer`);
+            }
+
+            try {
+                const evaluation = entry.instance.checkAnswer();
+                logTrace('checkAnswer', { interactionId, evaluation });
+
+                const config = entry.config;
+                if (!config.controlled) {
+                    try {
+                        recordInteractionResult(config, evaluation);
+                    } catch (recordError) {
+                        logger.warn(`[CourseCodeAutomation] Failed to record interaction "${interactionId}" to SCORM: ${recordError.message}`);
+                    }
+                }
+
+                return evaluation;
+            } catch (error) {
+                logTrace('checkAnswer:error', { interactionId, error: error.message });
+                throw new Error(`CourseCodeAutomation: Failed to check answer for "${interactionId}": ${error.message}`);
+            }
+        },
+
+        checkSlideAnswers(getCurrentSlide) {
+            const slideId = getCurrentSlide();
+            const slideInteractions = interactionRegistry.getAll();
+
+            if (slideInteractions.length === 0) {
+                logTrace('checkSlideAnswers', {
+                    slideId,
+                    found: 0,
+                    message: 'No interactions found on slide'
+                });
+                return [];
+            }
+
+            const results = [];
+            for (const interactionInfo of slideInteractions) {
+                try {
+                    const evaluation = this.checkAnswer(interactionInfo.id);
+                    results.push({
+                        interactionId: interactionInfo.id,
+                        type: interactionInfo.type,
+                        evaluation
+                    });
+                } catch (error) {
+                    results.push({
+                        interactionId: interactionInfo.id,
+                        type: interactionInfo.type,
+                        error: error.message
+                    });
+                }
+            }
+
+            logTrace('checkSlideAnswers', {
+                slideId,
+                total: slideInteractions.length,
+                successful: results.filter(r => !r.error).length,
+                failed: results.filter(r => r.error).length
+            });
+
+            return results;
+        }
+    };
+}

package/framework/js/automation/api.js

@@ -0,0 +1,242 @@
+/**
+ * @file api.js
+ * @description Public automation API exposed on window.CourseCodeAutomation
+ * Provides programmatic control over interactions, navigation, and course state
+ * for testing and AI-driven automation.
+ * 
+ * This module is ONLY loaded in development/testing mode and is completely excluded
+ * from production builds via Vite's tree-shaking.
+ * 
+ * Delegates to domain-specific modules:
+ *   api-interactions.js  – discovery, state, mutation, evaluation
+ *   api-engagement.js    – engagement, flags, audio
+ */
+
+import { logger } from '../utilities/logger.js';
+import { eventBus } from '../core/event-bus.js';
+import * as NavigationActions from '../navigation/NavigationActions.js';
+import { courseConfig } from '../../../course/course-config.js';
+import stateManager from '../state/index.js';
+import accessibilityManager from '../managers/accessibility-manager.js';
+import objectiveManager from '../managers/objective-manager.js';
+
+import { createInteractionMethods } from './api-interactions.js';
+import { createEngagementMethods } from './api-engagement.js';
+
+/** Automation trace log for observability */
+const automationTrace = [];
+
+/** Framework log buffer — captures structured log:warn and log:error events */
+const frameworkLogs = [];
+const MAX_FRAMEWORK_LOGS = 100;
+
+eventBus.on('log:warn', (payload) => {
+    frameworkLogs.push({ ...payload, timestamp: new Date().toISOString() });
+    if (frameworkLogs.length > MAX_FRAMEWORK_LOGS) frameworkLogs.shift();
+});
+eventBus.on('log:error', (payload) => {
+    frameworkLogs.push({ ...payload, timestamp: new Date().toISOString() });
+    if (frameworkLogs.length > MAX_FRAMEWORK_LOGS) frameworkLogs.shift();
+});
+
+/** Adds an entry to the automation trace log */
+function logTrace(action, details) {
+    const entry = {
+        timestamp: new Date().toISOString(),
+        action,
+        ...details
+    };
+    automationTrace.push(entry);
+    eventBus.emit('automation:trace', entry);
+}
+
+// Build delegated method sets
+const interactionMethods = createInteractionMethods(logTrace);
+const engagementMethods = createEngagementMethods(logTrace);
+
+/**
+ * CourseCodeAutomation API
+ * All methods throw errors on failure (no silent failures)
+ */
+const CourseCodeAutomationAPI = {
+    // ===== Discovery & Interaction Methods =====
+    listInteractions: interactionMethods.listInteractions,
+    getInteractionMetadata: interactionMethods.getInteractionMetadata,
+    getResponse: interactionMethods.getResponse,
+    getCorrectResponse: interactionMethods.getCorrectResponse,
+    setResponse: interactionMethods.setResponse,
+    checkAnswer: interactionMethods.checkAnswer,
+    checkSlideAnswers() {
+        return interactionMethods.checkSlideAnswers.call(
+            interactionMethods,
+            () => this.getCurrentSlide()
+        );
+    },
+
+    // ===== Navigation Methods =====
+
+    getToc() {
+        const toc = [];
+        const flatten = (items) => {
+            for (const item of items) {
+                if (item.type === 'section') {
+                    toc.push({ id: item.id, type: 'section', title: item.menu?.label });
+                    if (item.children) flatten(item.children);
+                } else {
+                    toc.push({ id: item.id, type: item.type, title: item.title, file: item.component });
+                }
+            }
+        };
+        flatten(courseConfig.structure);
+        logTrace('getToc', { count: toc.length });
+        return toc;
+    },
+
+    getCurrentSlide() {
+        const currentSlide = NavigationActions.getCurrentSlide();
+        logTrace('getCurrentSlide', { slideId: currentSlide?.id });
+        return currentSlide?.id || null;
+    },
+
+    async goToSlide(slideId, context = {}) {
+        try {
+            await NavigationActions.goToSlide(slideId, context);
+            logTrace('goToSlide', { slideId, context });
+        } catch (error) {
+            logTrace('goToSlide:error', { slideId, context, error: error.message });
+            throw new Error(`CourseCodeAutomation: Failed to navigate to "${slideId}": ${error.message}`);
+        }
+    },
+
+    // ===== Observability Methods =====
+
+    getAutomationTrace() {
+        return [...automationTrace];
+    },
+
+    clearAutomationTrace() {
+        const count = automationTrace.length;
+        automationTrace.length = 0;
+        logTrace('clearAutomationTrace', { clearedCount: count });
+        logger.debug(`[CourseCodeAutomation] Cleared ${count} trace entries`);
+    },
+
+    getFrameworkLogs() {
+        const logs = frameworkLogs.splice(0);
+        logTrace('getFrameworkLogs', { count: logs.length });
+        return logs;
+    },
+
+
+    // ===== Engagement Methods =====
+    getEngagementState: engagementMethods.getEngagementState,
+    getEngagementProgress: engagementMethods.getEngagementProgress,
+    markTabViewed: engagementMethods.markTabViewed,
+    markFlipCardViewed: engagementMethods.markFlipCardViewed,
+    setScrollDepth: engagementMethods.setScrollDepth,
+    resetEngagement: engagementMethods.resetEngagement,
+
+    // ===== Flag Management =====
+    getFlag: engagementMethods.getFlag,
+    setFlag: engagementMethods.setFlag,
+    getAllFlags: engagementMethods.getAllFlags,
+    removeFlag: engagementMethods.removeFlag,
+
+    // ===== Audio Methods =====
+    getAudioState: engagementMethods.getAudioState,
+    hasAudio: engagementMethods.hasAudio,
+    simulateAudioComplete: engagementMethods.simulateAudioComplete,
+    isAudioCompletedForContext: engagementMethods.isAudioCompletedForContext,
+    getAudioProgress: engagementMethods.getAudioProgress,
+
+    // ===== LMS State =====
+
+    /**
+     * Returns the full LMS data model:
+     * - Direct CMI writes: score, completion, success, bookmark
+     * - CMI-backed domains: objectives
+     * - All suspend_data domains: the full state blob
+     */
+    getLmsState() {
+        const score = stateManager.getScore();
+        const completion = stateManager.getCompletion();
+        const success = stateManager.getSuccess();
+        const bookmark = stateManager.getBookmark();
+        const format = stateManager.getFormat();
+
+        // Objectives from ObjectiveManager (driver-agnostic)
+        const rawObjectives = objectiveManager.getObjectives();
+        const objectives = {};
+        for (const obj of rawObjectives) {
+            objectives[obj.id] = {
+                completion_status: obj.completion_status,
+                success_status: obj.success_status,
+                score: obj.score ?? null
+            };
+        }
+
+        // Full suspend_data domains
+        const state = stateManager.getState();
+
+        logTrace('getLmsState', { format, hasScore: score !== null });
+
+        return {
+            score,
+            completion,
+            success,
+            bookmark,
+            format,
+            objectives,
+            state
+        };
+    },
+
+    // ===== Accessibility / Theme =====
+
+    /**
+     * Set an accessibility preference (theme, highContrast, largeFont, reducedMotion).
+     * @param {'theme'|'highContrast'|'largeFont'|'reducedMotion'} key
+     * @param {string|boolean} value - 'light'|'dark' for theme, boolean for others
+     */
+    setAccessibilityPreference(key, value) {
+        accessibilityManager.setPreference(key, value);
+        logTrace('setAccessibilityPreference', { key, value });
+    },
+
+    /**
+     * Get current accessibility state (theme, highContrast, largeFont, reducedMotion).
+     */
+    getAccessibilityState() {
+        const state = { ...accessibilityManager.state };
+        logTrace('getAccessibilityState', state);
+        return state;
+    },
+
+    // ===== Version Info =====
+
+    getVersion() {
+        return {
+            api: '2.2.0',
+            phase: 8,
+            features: [
+                'discovery',
+                'state-access',
+                'state-mutation',
+                'evaluation',
+                'navigation',
+                'observability',
+                'ergonomic-helpers',
+                'engagement-tracking',
+                'flip-card-tracking',
+                'flag-management',
+                'audio-state',
+                'audio-completion-simulation',
+                'framework-logs',
+                'lms-state',
+                'accessibility-preferences'
+            ]
+        };
+    }
+};
+
+export default CourseCodeAutomationAPI;

package/framework/js/automation/index.js

@@ -0,0 +1,41 @@
+/**
+ * @file index.js
+ * @description Entry point for the automation module.
+ * Initializes and exposes the CourseCodeAutomation API on window.
+ * 
+ * This entire module is ONLY loaded in development/testing mode when:
+ * 1. import.meta.env.MODE !== 'production'
+ * 2. courseConfig.environment.automation.enabled === true
+ * 
+ * In production builds, Vite's tree-shaking will completely eliminate this code.
+ */
+
+import CourseCodeAutomationAPI from './api.js';
+import { eventBus } from '../core/event-bus.js';
+import { logger } from '../utilities/logger.js';
+
+/**
+ * Initializes the automation system
+ * - Exposes window.CourseCodeAutomation API
+ * - Sets up event listeners for tracking
+ */
+export function initializeAutomation() {
+    logger.debug('[Automation] Initializing automation system...');
+
+    // Expose the API globally
+    window.CourseCodeAutomation = CourseCodeAutomationAPI;
+
+    // Log when interactions are registered
+    eventBus.on('interaction:registered', ({ id, type }) => {
+        logger.debug(`[Automation] ✓ Registered: ${id} (${type || 'unknown'})`);
+    });
+
+    logger.debug('[Automation] ✓ Automation system initialized');
+    logger.debug('[Automation] window.CourseCodeAutomation API is now available');
+    logger.debug('[Automation] Use window.CourseCodeAutomation.getVersion() for feature info');
+
+    // Emit initialization event
+    eventBus.emit('automation:initialized', {
+        version: CourseCodeAutomationAPI.getVersion()
+    });
+}