walkthrough-enhancement.js

// Enhanced Walkthrough Mode - Deep AI Education
// This file provides additional educational features for the walkthrough mode

// Enhanced training speed control for walkthrough mode
const walkthroughSpeeds = {
    'ultra_slow': 2000,    // 2 seconds between training steps - for detailed explanation
    'slow': 1000,          // 1 second - good for following along
    'normal': 500,         // 0.5 seconds - default walkthrough speed
    'fast': 200            // 0.2 seconds - faster but still educational
};

// Enhanced tutorial data with deeper explanations
const enhancedTutorials = {
    basics: {
        title: 'Neural Network Basics - Deep Dive',
        description: 'Understand every component of a neural network in detail',
        steps: [
            {
                title: 'Welcome to Neural Networks!',
                content: 'Neural networks are computational models inspired by biological neural networks. Each artificial neuron processes inputs, applies weights, adds bias, and produces an output through an activation function. Think of it as a simplified version of how brain neurons communicate!',
                element: null,
                position: 'center',
                duration: 5000,
                explanation: 'Neural networks revolutionized AI by mimicking how the brain processes information through interconnected neurons.'
            },
            {
                title: 'Input Layer - Data Entry Point',
                content: 'The input layer receives raw data. Each neuron holds one feature or dimension of your data. For images, this might be pixel values. For text, word embeddings. For logic gates, binary values (0 or 1). The values you see (like 0.00) represent the current activation of each input neuron.',
                element: '#networkCanvas',
                position: 'right',
                highlight: {x: 0, y: 0, width: 150, height: 300},
                duration: 8000,
                explanation: 'Input neurons don\'t perform calculations - they just hold and pass forward the data values.'
            },
            {
                title: 'Hidden Layers - The Thinking Process',
                content: 'Hidden layers are where the magic happens! Each neuron combines inputs from the previous layer using learned weights, adds a bias term, and applies an activation function (like ReLU). Multiple hidden layers allow the network to learn increasingly complex patterns and abstractions.',
                element: '#networkCanvas',
                position: 'right',
                highlight: {x: 150, y: 0, width: 200, height: 300},
                duration: 10000,
                explanation: 'Hidden layers transform input data through mathematical operations: z = Σ(weight × input) + bias, then activation = max(0, z) for ReLU.'
            },
            {
                title: 'Output Layer - The Final Decision',
                content: 'The output layer produces the final result. For classification, it uses sigmoid/softmax to output probabilities. For regression, it might use linear activation for continuous values. The number here represents the network\'s confidence or prediction value.',
                element: '#networkCanvas',
                position: 'left',
                highlight: {x: 350, y: 0, width: 100, height: 300},
                duration: 8000,
                explanation: 'Output layer neurons apply specific activation functions based on the task type (sigmoid for binary classification, softmax for multi-class).'
            }
        ]
    },
    
    training: {
        title: 'Training Process - Step by Step',
        description: 'Learn how neural networks learn through backpropagation',
        steps: [
            {
                title: 'The Learning Cycle Overview',
                content: 'Neural network training follows a cycle: 1) Forward pass (prediction), 2) Loss calculation (how wrong we are), 3) Backward pass (find gradients), 4) Weight updates (improve the network). This cycle repeats thousands of times until the network learns the pattern.',
                element: null,
                position: 'center',
                duration: 8000,
                explanation: 'This is the fundamental learning algorithm that powers all modern deep learning.'
            },
            {
                title: 'Forward Propagation - Making Predictions',
                content: 'Data flows left to right through the network. Each neuron receives inputs, multiplies by weights, adds bias, and applies activation function. Watch the numbers change as different training examples flow through - this is the network making predictions!',
                element: '#networkCanvas',
                position: 'bottom',
                duration: 10000,
                explanation: 'Forward pass: for each layer, output = activation_function(weights × inputs + bias)',
                action: 'highlight_forward_flow'
            },
            {
                title: 'Loss Calculation - Measuring Mistakes',
                content: 'Loss functions measure how far the prediction is from the correct answer. Mean Squared Error for regression: (predicted - actual)². Cross-entropy for classification. Lower loss = better predictions. The goal is to minimize this number!',
                element: '#lossValue',
                position: 'bottom',
                duration: 8000,
                explanation: 'Different tasks use different loss functions, but they all measure prediction error.'
            },
            {
                title: 'Backpropagation - Learning from Mistakes',
                content: 'Here\'s where the magic happens! The error propagates backward through the network using calculus (chain rule). Each weight learns how much it contributed to the error and adjusts accordingly. This is why it\'s called "backpropagation".',
                element: '#networkCanvas',
                position: 'bottom',
                duration: 12000,
                explanation: 'Backprop uses gradient descent: weight_new = weight_old - learning_rate × gradient',
                action: 'highlight_backward_flow'
            },
            {
                title: 'Weight Updates - Getting Smarter',
                content: 'Weights are updated using gradients and learning rate. Learning rate controls step size - too big and we overshoot, too small and learning is slow. Watch the connection colors change as weights adjust! Green = positive weights, Red = negative weights.',
                element: '#networkCanvas',
                position: 'top',
                duration: 10000,
                explanation: 'Optimal learning rate is crucial - it\'s often found through experimentation or adaptive methods like Adam.'
            }
        ]
    },
    
    visualization: {
        title: 'Understanding Visualizations - Read the AI\'s Mind',
        description: 'Learn to interpret every visual element of the training process',
        steps: [
            {
                title: 'Network Diagram - The AI Brain Map',
                content: 'This diagram shows the current state of every neuron and connection. Circle brightness = activation level (how excited the neuron is). Line thickness = weight strength (how much influence). Colors help distinguish layers and positive/negative weights.',
                element: '#networkCanvas',
                position: 'bottom',
                duration: 10000,
                explanation: 'Real-time visualization helps you understand what the network is "thinking" at each moment.'
            },
            {
                title: 'Neuron Activations - Digital Excitement',
                content: 'Numbers inside neurons show activation values (0.00 to 1.00). Higher values mean the neuron is more "activated" or "excited" by the current input. Watch how these values change with different training examples!',
                element: '#networkCanvas',
                position: 'right',
                duration: 8000,
                explanation: 'Activation values flow through the network like electrical signals in a brain.'
            },
            {
                title: 'Connection Weights - Learned Knowledge',
                content: 'Green lines = positive weights (excitatory connections), Red lines = negative weights (inhibitory connections). Thicker lines = stronger connections. These weights encode everything the network has learned!',
                element: '#networkCanvas',
                position: 'right',
                duration: 10000,
                explanation: 'Weights are the network\'s memory - they store all learned patterns and relationships.'
            },
            {
                title: 'Loss Chart - Learning Progress',
                content: 'This chart is like the network\'s report card! Y-axis shows error level, X-axis shows training progress. The line should generally go down (getting better). Plateaus mean learning has slowed or stopped.',
                element: '#lossChart',
                position: 'left',
                duration: 8000,
                explanation: 'Loss curves tell the story of learning - steep drops mean rapid improvement, flat lines mean stability or convergence.'
            },
            {
                title: 'Training Statistics - Performance Dashboard',
                content: 'Epochs = training cycles completed. Loss = current error level. Accuracy = percentage correct. Current = which example we\'re learning from. These metrics tell you exactly how well the AI is performing!',
                element: '.stats-grid',
                position: 'bottom',
                duration: 10000,
                explanation: 'Monitoring these metrics helps diagnose training problems and track progress.'
            },
            {
                title: 'Prediction Results - The Moment of Truth',
                content: 'Each card shows a training example. Raw = actual network output. Predicted = final decision. Status = correct/wrong. Green border = correct prediction, Red = wrong, Blue = currently training on this example.',
                element: '#taskOutput',
                position: 'top',
                duration: 10000,
                explanation: 'This is where you see the network\'s actual performance on each individual example.'
            }
        ]
    },
    
    logic: {
        title: 'Logic Gates - Building Blocks of Computing',
        description: 'See how neural networks learn the fundamental operations of digital computers',
        steps: [
            {
                title: 'Logic Gates - Foundation of Computing',
                content: 'Logic gates are the building blocks of all digital computers! They take binary inputs (0 or 1) and produce binary outputs following simple rules. Neural networks can learn these rules from examples, just like learning any other pattern.',
                element: null,
                position: 'center',
                duration: 8000,
                explanation: 'Every computer operation, from simple arithmetic to complex AI, ultimately relies on combinations of these basic logic gates.'
            },
            {
                title: 'AND Gate - Both Must Be True',
                content: 'AND outputs 1 only when BOTH inputs are 1. Like saying "I\'ll go outside if it\'s sunny AND warm." This pattern is "linearly separable" - you can draw a straight line to separate the 0s from the 1s, making it easy for neural networks to learn.',
                element: '#taskOutput',
                position: 'top',
                duration: 10000,
                explanation: 'Linear separability means a simple perceptron (single layer) can solve this problem.'
            },
            {
                title: 'OR Gate - At Least One Must Be True',
                content: 'OR outputs 1 when at least one input is 1. Like "I\'ll be happy if I have coffee OR chocolate." Also linearly separable, so it learns quickly. Watch how the network adjusts to recognize this different pattern!',
                element: '#taskOutput',
                position: 'top',
                duration: 8000,
                explanation: 'OR and AND gates have different decision boundaries but both are linearly separable.'
            },
            {
                title: 'XOR Gate - The Challenge',
                content: 'XOR (exclusive OR) outputs 1 when inputs are different. This is NOT linearly separable! You can\'t draw a single straight line to separate the patterns. This is why we need multiple layers - hidden layers create complex decision boundaries.',
                element: '#taskOutput',
                position: 'top',
                duration: 12000,
                explanation: 'XOR was historically important because it proved that multi-layer networks were necessary for complex problems.'
            },
            {
                title: 'Why Multiple Layers Matter',
                content: 'Hidden layers transform the input space, making non-linear problems solvable. The first hidden layer might separate some patterns, the second layer combines those patterns in new ways. Each layer adds expressive power!',
                element: '#networkCanvas',
                position: 'bottom',
                duration: 10000,
                explanation: 'Universal approximation theorem: neural networks with enough hidden units can approximate any continuous function.'
            }
        ]
    }
};

// Walkthrough state management
let walkthroughState = {
    active: false,
    currentTutorial: null,
    currentStep: 0,
    autoPlay: false,
    speed: 'normal'
};

// DOM elements for walkthrough
const walkthroughElements = {
    overlay: null,
    highlight: null,
    popup: null,
    progress: null,
    indicator: null
};

// Initialize walkthrough elements
function initializeWalkthrough() {
    // Get DOM elements
    walkthroughElements.overlay = document.getElementById('walkthroughOverlay');
    walkthroughElements.highlight = document.getElementById('walkthroughHighlight');
    walkthroughElements.popup = document.getElementById('walkthroughPopup');
    walkthroughElements.progress = document.getElementById('walkthroughProgress');
    walkthroughElements.indicator = document.getElementById('walkthroughIndicator');
    
    // Set up event listeners
    setupWalkthroughEventListeners();
}

// Setup event listeners for walkthrough
function setupWalkthroughEventListeners() {
    // Previous button
    const prevBtn = document.getElementById('walkthroughPrev');
    if (prevBtn) {
        prevBtn.addEventListener('click', () => {
            if (walkthroughState.currentStep > 0) {
                walkthroughState.currentStep--;
                updateWalkthroughStep();
            }
        });
    }
    
    // Next button
    const nextBtn = document.getElementById('walkthroughNext');
    if (nextBtn) {
        nextBtn.addEventListener('click', () => {
            const tutorial = enhancedTutorials[walkthroughState.currentTutorial];
            if (walkthroughState.currentStep < tutorial.steps.length - 1) {
                walkthroughState.currentStep++;
                updateWalkthroughStep();
            } else {
                endWalkthrough();
            }
        });
    }
    
    // Skip/Exit button
    const skipBtn = document.getElementById('walkthroughSkip');
    if (skipBtn) {
        skipBtn.addEventListener('click', endWalkthrough);
    }
    
    // Overlay click to exit
    if (walkthroughElements.overlay) {
        walkthroughElements.overlay.addEventListener('click', (e) => {
            if (e.target === walkthroughElements.overlay) {
                endWalkthrough();
            }
        });
    }
    
    // Keyboard navigation
    document.addEventListener('keydown', (e) => {
        if (!walkthroughState.active) return;
        
        switch(e.key) {
            case 'ArrowLeft':
                e.preventDefault();
                if (walkthroughState.currentStep > 0) {
                    walkthroughState.currentStep--;
                    updateWalkthroughStep();
                }
                break;
            case 'ArrowRight':
                e.preventDefault();
                const tutorial = enhancedTutorials[walkthroughState.currentTutorial];
                if (walkthroughState.currentStep < tutorial.steps.length - 1) {
                    walkthroughState.currentStep++;
                    updateWalkthroughStep();
                } else {
                    endWalkthrough();
                }
                break;
            case 'Escape':
                e.preventDefault();
                endWalkthrough();
                break;
        }
    });
}

// Start a specific walkthrough tutorial
function startWalkthrough(tutorialId) {
    console.log('Starting walkthrough:', tutorialId);
    
    // Check if tutorial exists
    if (!enhancedTutorials[tutorialId]) {
        console.error('Tutorial not found:', tutorialId);
        return;
    }
    
    // Start with AND gate for logic tutorial
    if (tutorialId === 'logic') {
        selectTask('and'); // This should trigger the AND gate task
        setTimeout(() => {
            startWalkthroughOnTask(tutorialId);
        }, 100);
    } else {
        startWalkthroughOnTask(tutorialId);
    }
}

// Start walkthrough on current task
function startWalkthroughOnTask(tutorialId) {
    walkthroughState.active = true;
    walkthroughState.currentTutorial = tutorialId;
    walkthroughState.currentStep = 0;
    
    // Show overlay and indicator
    if (walkthroughElements.overlay) {
        walkthroughElements.overlay.style.display = 'block';
    }
    if (walkthroughElements.indicator) {
        walkthroughElements.indicator.style.display = 'block';
    }
    
    // Hide walkthrough mode menu
    const walkthroughMode = document.getElementById('walkthroughMode');
    if (walkthroughMode) {
        walkthroughMode.style.display = 'none';
    }
    
    // Show training interface if not already shown
    const trainingInterface = document.getElementById('trainingInterface');
    if (trainingInterface && trainingInterface.style.display === 'none') {
        trainingInterface.style.display = 'block';
    }
    
    updateWalkthroughStep();
}

// Update the current walkthrough step
function updateWalkthroughStep() {
    const tutorial = enhancedTutorials[walkthroughState.currentTutorial];
    const step = tutorial.steps[walkthroughState.currentStep];
    
    if (!step) return;
    
    // Update progress indicator
    if (walkthroughElements.progress) {
        walkthroughElements.progress.style.display = 'block';
        document.getElementById('walkthroughStep').textContent = walkthroughState.currentStep + 1;
        document.getElementById('walkthroughTotal').textContent = tutorial.steps.length;
    }
    
    // Update popup content
    if (walkthroughElements.popup) {
        document.getElementById('walkthroughTitle').textContent = step.title;
        document.getElementById('walkthroughContent').textContent = step.content;
        
        // Position popup
        positionWalkthroughPopup(step);
        
        // Show popup
        walkthroughElements.popup.style.display = 'block';
    }
    
    // Update highlight
    if (step.element && step.highlight) {
        highlightElement(step.element, step.highlight);
    } else if (step.element) {
        highlightElement(step.element);
    } else {
        // Center mode - no specific element highlighted
        if (walkthroughElements.highlight) {
            walkthroughElements.highlight.style.display = 'none';
        }
    }
    
    // Update button states
    const prevBtn = document.getElementById('walkthroughPrev');
    const nextBtn = document.getElementById('walkthroughNext');
    
    if (prevBtn) {
        prevBtn.disabled = walkthroughState.currentStep === 0;
        prevBtn.style.opacity = walkthroughState.currentStep === 0 ? '0.5' : '1';
    }
    
    if (nextBtn) {
        const isLastStep = walkthroughState.currentStep === tutorial.steps.length - 1;
        nextBtn.textContent = isLastStep ? 'Finish' : 'Next';
    }
}

// Position the walkthrough popup
function positionWalkthroughPopup(step) {
    const popup = walkthroughElements.popup;
    if (!popup) return;
    
    // Remove all position classes
    popup.className = 'walkthrough-popup';
    
    if (step.position === 'center') {
        // Center the popup
        popup.style.position = 'fixed';
        popup.style.top = '50%';
        popup.style.left = '50%';
        popup.style.transform = 'translate(-50%, -50%)';
        popup.style.maxWidth = '90vw';
    } else if (step.element) {
        const element = document.querySelector(step.element);
        if (element) {
            const rect = element.getBoundingClientRect();
            
            popup.style.position = 'fixed';
            popup.style.transform = 'none';
            
            switch(step.position) {
                case 'top':
                    popup.style.left = `${rect.left + rect.width / 2 - 175}px`;
                    popup.style.top = `${rect.top - 200}px`;
                    popup.className += ' top';
                    break;
                case 'bottom':
                    popup.style.left = `${rect.left + rect.width / 2 - 175}px`;
                    popup.style.top = `${rect.bottom + 20}px`;
                    popup.className += ' bottom';
                    break;
                case 'left':
                    popup.style.left = `${rect.left - 370}px`;
                    popup.style.top = `${rect.top + rect.height / 2 - 100}px`;
                    popup.className += ' left';
                    break;
                case 'right':
                    popup.style.left = `${rect.right + 20}px`;
                    popup.style.top = `${rect.top + rect.height / 2 - 100}px`;
                    popup.className += ' right';
                    break;
            }
            
            // Ensure popup stays within viewport
            const popupRect = popup.getBoundingClientRect();
            if (popupRect.right > window.innerWidth) {
                popup.style.left = `${window.innerWidth - popupRect.width - 20}px`;
            }
            if (popupRect.left < 0) {
                popup.style.left = '20px';
            }
            if (popupRect.bottom > window.innerHeight) {
                popup.style.top = `${window.innerHeight - popupRect.height - 20}px`;
            }
            if (popupRect.top < 0) {
                popup.style.top = '20px';
            }
        }
    }
}

// Highlight a specific element
function highlightElement(selector, customBounds = null) {
    const element = document.querySelector(selector);
    const highlight = walkthroughElements.highlight;
    
    if (!element || !highlight) return;
    
    const rect = element.getBoundingClientRect();
    
    let bounds = {
        x: rect.left,
        y: rect.top,
        width: rect.width,
        height: rect.height
    };
    
    // Use custom bounds if provided (for highlighting parts of elements)
    if (customBounds) {
        bounds = {
            x: rect.left + customBounds.x,
            y: rect.top + customBounds.y,
            width: customBounds.width,
            height: customBounds.height
        };
    }
    
    // Position the highlight
    highlight.style.display = 'block';
    highlight.style.left = `${bounds.x - 5}px`;
    highlight.style.top = `${bounds.y - 5}px`;
    highlight.style.width = `${bounds.width + 10}px`;
    highlight.style.height = `${bounds.height + 10}px`;
}

// End the walkthrough
function endWalkthrough() {
    walkthroughState.active = false;
    walkthroughState.currentTutorial = null;
    walkthroughState.currentStep = 0;
    
    // Hide all walkthrough elements
    if (walkthroughElements.overlay) {
        walkthroughElements.overlay.style.display = 'none';
    }
    if (walkthroughElements.highlight) {
        walkthroughElements.highlight.style.display = 'none';
    }
    if (walkthroughElements.popup) {
        walkthroughElements.popup.style.display = 'none';
    }
    if (walkthroughElements.progress) {
        walkthroughElements.progress.style.display = 'none';
    }
    if (walkthroughElements.indicator) {
        walkthroughElements.indicator.style.display = 'none';
    }
    
    // Return to walkthrough mode menu
    const walkthroughMode = document.getElementById('walkthroughMode');
    if (walkthroughMode) {
        walkthroughMode.style.display = 'block';
    }
    
    // Hide training interface if we were in walkthrough
    const trainingInterface = document.getElementById('trainingInterface');
    if (trainingInterface) {
        trainingInterface.style.display = 'none';
    }
}

// Initialize when the page loads
document.addEventListener('DOMContentLoaded', () => {
    console.log('Initializing walkthrough system...');
    initializeWalkthrough();
});

// Make functions globally available
window.startWalkthrough = startWalkthrough;
window.endWalkthrough = endWalkthrough;
window.walkthroughState = walkthroughState;