From 944ac896f219254402936fdbc94cc15f278462c2 Mon Sep 17 00:00:00 2001
From: supervoidcoder <88671013+supervoidcoder@users.noreply.github.com>
Date: Tue, 2 Dec 2025 00:19:20 +0000
Subject: [PATCH 1/7] feat: add welcome modal

---
 src/components/gui/gui.jsx                    |  10 +-
 src/components/welcome-modal/addons-step.css  |  71 +++++++
 src/components/welcome-modal/addons-step.jsx  |  46 +++++
 src/components/welcome-modal/final-step.css   | 110 ++++++++++
 src/components/welcome-modal/final-step.jsx   |  57 ++++++
 src/components/welcome-modal/theme-step.css   | 125 ++++++++++++
 src/components/welcome-modal/theme-step.jsx   | 149 ++++++++++++++
 .../welcome-modal/welcome-modal.css           | 134 ++++++++++++
 .../welcome-modal/welcome-modal.jsx           | 193 ++++++++++++++++++
 src/components/welcome-modal/welcome-step.css |  89 ++++++++
 src/components/welcome-modal/welcome-step.jsx |  58 ++++++
 src/containers/gui.jsx                        |   7 +-
 12 files changed, 1047 insertions(+), 2 deletions(-)
 create mode 100644 src/components/welcome-modal/addons-step.css
 create mode 100644 src/components/welcome-modal/addons-step.jsx
 create mode 100644 src/components/welcome-modal/final-step.css
 create mode 100644 src/components/welcome-modal/final-step.jsx
 create mode 100644 src/components/welcome-modal/theme-step.css
 create mode 100644 src/components/welcome-modal/theme-step.jsx
 create mode 100644 src/components/welcome-modal/welcome-modal.css
 create mode 100644 src/components/welcome-modal/welcome-modal.jsx
 create mode 100644 src/components/welcome-modal/welcome-step.css
 create mode 100644 src/components/welcome-modal/welcome-step.jsx

diff --git a/src/components/gui/gui.jsx b/src/components/gui/gui.jsx
index a96c5f16c..daff0481a 100644
--- a/src/components/gui/gui.jsx
+++ b/src/components/gui/gui.jsx
@@ -8,7 +8,7 @@ import MediaQuery from 'react-responsive';
 import {Tab, Tabs, TabList, TabPanel} from 'react-tabs';
 import tabStyles from 'react-tabs/style/react-tabs.css';
 import VM from 'scratch-vm';
-
+import WelcomeModal from '../welcome-modal/welcome-modal.jsx';
 import Blocks from '../../containers/blocks.jsx';
 import CostumeTab from '../../containers/costume-tab.jsx';
 import TargetPane from '../../containers/target-pane.jsx';
@@ -160,9 +160,11 @@ const GUIComponent = props => {
         fontsModalVisible,
         unknownPlatformModalVisible,
         invalidProjectModalVisible,
+        showWelcomeModal,
         vm,
         ...componentProps
     } = omit(props, 'dispatch');
+    console.log('🎯 showWelcomeModal:', showWelcomeModal);
     if (children) {
         return <Box {...componentProps}>{children}</Box>;
     }
@@ -238,6 +240,10 @@ const GUIComponent = props => {
                 {...componentProps}
             >
                 {alwaysEnabledModals}
+                {showWelcomeModal ? (
+                <WelcomeModal
+                    onRequestClose={onRequestCloseWelcomeModal} />
+                    ) : null}
                 {telemetryModalVisible ? (
                     <TelemetryModal
                         isRtl={isRtl}
@@ -557,6 +563,8 @@ GUIComponent.propTypes = {
     customExtensionModalVisible: PropTypes.bool,
     fontsModalVisible: PropTypes.bool,
     unknownPlatformModalVisible: PropTypes.bool,
+    showWelcomeModal: PropTypes.bool, 
+    onRequestCloseWelcomeModal: PropTypes.func,
     invalidProjectModalVisible: PropTypes.bool,
     vm: PropTypes.instanceOf(VM).isRequired
 };
diff --git a/src/components/welcome-modal/addons-step.css b/src/components/welcome-modal/addons-step.css
new file mode 100644
index 000000000..c93df66e3
--- /dev/null
+++ b/src/components/welcome-modal/addons-step.css
@@ -0,0 +1,71 @@
+.addons-step {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+}
+
+.header {
+    flex: 0 0 auto;
+    display: flex;
+    align-items: center;
+    gap: 1.5rem;
+    margin-bottom: 1.5rem;
+}
+
+.illustration-container {
+    flex-shrink: 0;
+}
+
+.illustration-placeholder {
+    font-size: 3rem;
+    padding: 1rem;
+    background: linear-gradient(135deg, #0FBD8C 0%, #0DA57A 100%);
+    border-radius: 12px;
+    color: white;
+}
+
+.header-text {
+    flex: 1;
+    text-align: left;
+}
+
+.title {
+    font-size: 2rem;
+    font-weight: 800;
+    margin: 0 0 0.5rem 0;
+    color: #333;
+}
+
+.subtitle {
+    font-size: 1.1rem;
+    color: #666;
+    margin: 0;
+}
+
+/* Iframe container */
+.iframe-container {
+    flex: 1;
+    border: 2px solid #e0e0e0;
+    border-radius: 12px;
+    overflow: hidden;
+    background: white;
+}
+
+.addons-iframe {
+    width: 100%;
+    height: 100%;
+    border: none;
+}
+
+/* Footer */
+.footer {
+    flex: 0 0 auto;
+    margin-top: 1rem;
+    text-align: center;
+}
+
+.footer-note {
+    margin: 0;
+    font-size: 0.9rem;
+    color: #999;
+}
\ No newline at end of file
diff --git a/src/components/welcome-modal/addons-step.jsx b/src/components/welcome-modal/addons-step.jsx
new file mode 100644
index 000000000..67eac29b9
--- /dev/null
+++ b/src/components/welcome-modal/addons-step.jsx
@@ -0,0 +1,46 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import styles from './addons-step.css';
+
+const AddonsStep = () => (
+    <div className={styles.addonsStep}>
+        <div className={styles.header}>
+            <div className={styles.illustrationContainer}>
+                {/* Your SVG illustration goes here! */}
+                <div className={styles.illustrationPlaceholder}>
+                    🧩 Your addons SVG illustration here!
+                </div>
+            </div>
+
+            <div className={styles.headerText}>
+                <h2 className={styles.title}>Set Up Your Addons 🧩</h2>
+                <p className={styles.subtitle}>
+                    Customize OmniBlocks with powerful extensions
+                </p>
+            </div>
+        </div>
+
+        <div className={styles.iframeContainer}>
+            <iframe
+                className={styles.addonsIframe}
+                src="/addons"
+                title="Addons Setup"
+                sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-modals allow-storage-access-by-user-activation"
+            />
+        </div>
+
+        <div className={styles.footer}>
+            <p className={styles.footerNote}>
+                💡 Don't worry, you can change these anytime in Settings!
+            </p>
+        </div>
+    </div>
+);
+
+AddonsStep.propTypes = {
+    onNext: PropTypes.func,
+    isFirstStep: PropTypes.bool,
+    isLastStep: PropTypes.bool
+};
+
+export default AddonsStep;
\ No newline at end of file
diff --git a/src/components/welcome-modal/final-step.css b/src/components/welcome-modal/final-step.css
new file mode 100644
index 000000000..8ee17c89b
--- /dev/null
+++ b/src/components/welcome-modal/final-step.css
@@ -0,0 +1,110 @@
+.final-step {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    height: 100%;
+    text-align: center;
+}
+
+.illustration-container {
+    flex: 0 0 auto;
+    margin-bottom: 2rem;
+}
+
+.illustration-placeholder {
+    font-size: 4rem;
+    padding: 2rem;
+    background: linear-gradient(135deg, #FFAB19 0%, #FF6B6B 100%);
+    border-radius: 16px;
+    color: white;
+}
+
+.content {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+}
+
+.title {
+    font-size: 3rem;
+    font-weight: 900;
+    margin: 0 0 1rem 0;
+    color: #333;
+}
+
+.subtitle {
+    font-size: 1.25rem;
+    color: #666;
+    margin: 0 0 2rem 0;
+}
+
+/* Tips section */
+.tips-section {
+    background: #f8f9fa;
+    border-radius: 12px;
+    padding: 1.5rem;
+    margin: 2rem auto;
+    max-width: 500px;
+}
+
+.tips-title {
+    font-size: 1.25rem;
+    font-weight: 700;
+    margin: 0 0 1rem 0;
+    color: #333;
+}
+
+.tips {
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+}
+
+.tip {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    text-align: left;
+    padding: 0.5rem;
+}
+
+.tip-icon {
+    font-size: 1.5rem;
+    flex-shrink: 0;
+}
+
+/* Celebration */
+.celebration {
+    margin-top: 2rem;
+    display: flex;
+    gap: 1rem;
+    justify-content: center;
+    font-size: 2rem;
+}
+
+.emoji {
+    animation: bounce 1s infinite;
+}
+
+.emoji:nth-child(2) {
+    animation-delay: 0.1s;
+}
+
+.emoji:nth-child(3) {
+    animation-delay: 0.2s;
+}
+
+.emoji:nth-child(4) {
+    animation-delay: 0.3s;
+}
+
+@keyframes bounce {
+    0%, 100% {
+        transform: translateY(0);
+    }
+    50% {
+        transform: translateY(-10px);
+    }
+}
\ No newline at end of file
diff --git a/src/components/welcome-modal/final-step.jsx b/src/components/welcome-modal/final-step.jsx
new file mode 100644
index 000000000..1f1d12866
--- /dev/null
+++ b/src/components/welcome-modal/final-step.jsx
@@ -0,0 +1,57 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import styles from './final-step.css';
+
+const FinalStep = () => (
+    <div className={styles.finalStep}>
+        <div className={styles.illustrationContainer}>
+            {/* Your SVG illustration goes here! */}
+            <div className={styles.illustrationPlaceholder}>
+                🚀 Your final SVG illustration here!
+            </div>
+        </div>
+
+        <div className={styles.content}>
+            <h1 className={styles.title}>
+                You're All Set! 🎉
+            </h1>
+            
+            <p className={styles.subtitle}>
+                Ready to start creating amazing projects?
+            </p>
+
+            <div className={styles.tipsSection}>
+                <h3 className={styles.tipsTitle}>Quick Tips 💡</h3>
+                <div className={styles.tips}>
+                    <div className={styles.tip}>
+                        <span className={styles.tipIcon}>⚙️</span>
+                        <span>Access settings anytime from the menu bar</span>
+                    </div>
+                    <div className={styles.tip}>
+                        <span className={styles.tipIcon}>📚</span>
+                        <span>Check out tutorials to learn advanced features</span>
+                    </div>
+                    <div className={styles.tip}>
+                        <span className={styles.tipIcon}>💾</span>
+                        <span>Remember to save your projects regularly</span>
+                    </div>
+                </div>
+            </div>
+
+            <div className={styles.celebration}>
+                <span className={styles.emoji}>🎊</span>
+                <span className={styles.emoji}>✨</span>
+                <span className={styles.emoji}>🎨</span>
+                <span className={styles.emoji}>🚀</span>
+            </div>
+        </div>
+    </div>
+);
+
+FinalStep.propTypes = {
+    onFinish: PropTypes.func,
+    isFirstStep: PropTypes.bool,
+    isLastStep: PropTypes.bool
+};
+
+export default FinalStep;
\ No newline at end of file
diff --git a/src/components/welcome-modal/theme-step.css b/src/components/welcome-modal/theme-step.css
new file mode 100644
index 000000000..18f34d479
--- /dev/null
+++ b/src/components/welcome-modal/theme-step.css
@@ -0,0 +1,125 @@
+.theme-step {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    height: 100%;
+}
+
+.illustration-container {
+    flex: 0 0 auto;
+    margin-bottom: 2rem;
+}
+
+.illustration-placeholder {
+    font-size: 3rem;
+    padding: 1.5rem 3rem;
+    background: linear-gradient(135deg, #FF6B6B 0%, #FF8E53 100%);
+    border-radius: 12px;
+    color: white;
+}
+
+.content {
+    flex: 1;
+    width: 100%;
+    max-width: 600px;
+    text-align: center;
+}
+
+.title {
+    font-size: 2rem;
+    font-weight: 800;
+    margin: 0 0 0.5rem 0;
+    color: #333;
+}
+
+.subtitle {
+    font-size: 1.1rem;
+    color: #666;
+    margin: 0 0 2rem 0;
+}
+
+/* Theme selector */
+.theme-selector {
+    display: flex;
+    gap: 1rem;
+    justify-content: center;
+    margin-bottom: 3rem;
+}
+
+.theme-option {
+    flex: 1;
+    max-width: 200px;
+    padding: 1.5rem;
+    background: #f8f9fa;
+    border: 3px solid transparent;
+    border-radius: 12px;
+    cursor: pointer;
+    transition: all 0.2s ease;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 1rem;
+}
+
+.theme-option:hover {
+    transform: translateY(-4px);
+    box-shadow: 0 8px 20px rgba(0, 0, 0, 0.1);
+}
+
+.theme-option.selected {
+    border-color: #4C97FF;
+    background: #EBF5FF;
+}
+
+.theme-preview {
+    font-size: 3rem;
+}
+
+/* Accent color picker */
+.accent-section {
+    margin-top: 2rem;
+}
+
+.accent-title {
+    font-size: 1.25rem;
+    font-weight: 700;
+    margin: 0 0 1rem 0;
+    color: #333;
+}
+
+.color-grid {
+    display: flex;
+    gap: 1rem;
+    justify-content: center;
+    flex-wrap: wrap;
+}
+
+.color-option {
+    width: 60px;
+    height: 60px;
+    border-radius: 50%;
+    border: 3px solid transparent;
+    cursor: pointer;
+    transition: all 0.2s ease;
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.color-option:hover {
+    transform: scale(1.1);
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
+}
+
+.color-option.selected-color {
+    border-color: #333;
+    box-shadow: 0 0 0 2px white, 0 0 0 5px #333;
+}
+
+.checkmark {
+    color: white;
+    font-size: 1.5rem;
+    font-weight: bold;
+    text-shadow: 0 2px 4px rgba(0, 0, 0, 0.3);
+}
\ No newline at end of file
diff --git a/src/components/welcome-modal/theme-step.jsx b/src/components/welcome-modal/theme-step.jsx
new file mode 100644
index 000000000..7b52bfe08
--- /dev/null
+++ b/src/components/welcome-modal/theme-step.jsx
@@ -0,0 +1,149 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import bindAll from 'lodash.bindall';
+import {connect} from 'react-redux';
+import {setTheme} from '../../reducers/theme';
+import {persistTheme} from '../../lib/themes/themePersistance';
+import {
+    Theme,
+    ACCENT_AQUA,
+    ACCENT_PURPLE,
+    ACCENT_BLUE,
+    ACCENT_RED,
+    ACCENT_RAINBOW,
+    GUI_LIGHT,
+    GUI_DARK
+} from '../../lib/themes';
+import styles from './theme-step.css';
+
+class ThemeStep extends React.Component {
+    constructor (props) {
+        super(props);
+        bindAll(this, [
+            'handleGuiChange',
+            'handleAccentChange'
+        ]);
+
+        // Available accent colors with display info
+        this.accentColors = [
+            {id: ACCENT_AQUA, name: 'Aqua', color: '#59C0C0'},
+            {id: ACCENT_PURPLE, name: 'Purple', color: '#9966FF'},
+            {id: ACCENT_BLUE, name: 'Blue', color: '#4C97FF'},
+            {id: ACCENT_RED, name: 'Red', color: '#FF6680'},
+            {id: ACCENT_RAINBOW, name: 'Rainbow', color: 'linear-gradient(90deg, #ff0000, #ff9a00, #d0de21, #4fdc4a, #3fdad8, #2fc9e2, #1c7fee, #5f15f2, #ba0cf8, #fb07d9)'}
+        ];
+    }
+
+    handleGuiChange (newGui) {
+        const newTheme = this.props.theme.set('gui', newGui);
+        this.props.onSetTheme(newTheme);
+        persistTheme(newTheme);
+    }
+
+    handleAccentChange (newAccent) {
+        const newTheme = this.props.theme.set('accent', newAccent);
+        this.props.onSetTheme(newTheme);
+        persistTheme(newTheme);
+    }
+
+    render () {
+        const currentGui = this.props.theme.gui;
+        const currentAccent = this.props.theme.accent;
+
+        return (
+            <div className={styles.themeStep}>
+                <div className={styles.illustrationContainer}>
+                    {/* Your SVG illustration goes here! */}
+                    <div className={styles.illustrationPlaceholder}>
+                        🎨 Your theme SVG illustration here!
+                    </div>
+                </div>
+
+                <div className={styles.content}>
+                    <h2 className={styles.title}>Choose Your Theme 🎨</h2>
+                    <p className={styles.subtitle}>
+                        Pick a look that matches your style
+                    </p>
+
+                    {/* Light/Dark Toggle */}
+                    <div className={styles.themeSelector}>
+                        <button
+                            className={
+                                currentGui === GUI_LIGHT ?
+                                    `${styles.themeOption} ${styles.selected}` :
+                                    styles.themeOption
+                            }
+                            onClick={() => this.handleGuiChange(GUI_LIGHT)}
+                        >
+                            <div className={styles.themePreview}>
+                                ☀️
+                            </div>
+                            <span>Light Mode</span>
+                        </button>
+
+                        <button
+                            className={
+                                currentGui === GUI_DARK ?
+                                    `${styles.themeOption} ${styles.selected}` :
+                                    styles.themeOption
+                            }
+                            onClick={() => this.handleGuiChange(GUI_DARK)}
+                        >
+                            <div className={styles.themePreview}>
+                                🌙
+                            </div>
+                            <span>Dark Mode</span>
+                        </button>
+                    </div>
+
+                    {/* Accent Color Picker */}
+                    <div className={styles.accentSection}>
+                        <h3 className={styles.accentTitle}>Accent Color</h3>
+                        <div className={styles.colorGrid}>
+                            {this.accentColors.map(({id, name, color}) => (
+                                <button
+                                    key={id}
+                                    className={
+                                        currentAccent === id ?
+                                            `${styles.colorOption} ${styles.selectedColor}` :
+                                            styles.colorOption
+                                    }
+                                    style={{
+                                        background: color
+                                    }}
+                                    onClick={() => this.handleAccentChange(id)}
+                                    title={name}
+                                >
+                                    {currentAccent === id && (
+                                        <span className={styles.checkmark}>✓</span>
+                                    )}
+                                </button>
+                            ))}
+                        </div>
+                    </div>
+                </div>
+            </div>
+        );
+    }
+}
+
+ThemeStep.propTypes = {
+    theme: PropTypes.instanceOf(Theme).isRequired,
+    onSetTheme: PropTypes.func.isRequired,
+    onNext: PropTypes.func,
+    isFirstStep: PropTypes.bool,
+    isLastStep: PropTypes.bool
+};
+
+const mapStateToProps = state => ({
+    theme: state.scratchGui.theme.theme
+});
+
+const mapDispatchToProps = dispatch => ({
+    onSetTheme: theme => dispatch(setTheme(theme))
+});
+
+export default connect(
+    mapStateToProps,
+    mapDispatchToProps
+)(ThemeStep);
\ No newline at end of file
diff --git a/src/components/welcome-modal/welcome-modal.css b/src/components/welcome-modal/welcome-modal.css
new file mode 100644
index 000000000..cd0d46831
--- /dev/null
+++ b/src/components/welcome-modal/welcome-modal.css
@@ -0,0 +1,134 @@
+@import "../../css/colors.css";
+@import "../../css/units.css";
+
+.modal-overlay {
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    background: rgba(0, 0, 0, 0.75);
+    z-index: 9999;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.modal-content {
+    background: white;
+    border-radius: 16px;
+    width: 90%;
+    max-width: 900px;
+    max-height: 90vh;
+    overflow: hidden;
+    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
+    outline: none;
+}
+
+.container {
+    display: flex;
+    flex-direction: column;
+    height: 600px;
+}
+
+/* Step indicator dots */
+.step-indicator {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    gap: 12px;
+    padding: 1.5rem 0;
+    background: linear-gradient(to bottom, #f8f9fa, white);
+}
+
+.step-dot,
+.step-dot-active,
+.step-dot-completed {
+    width: 12px;
+    height: 12px;
+    border-radius: 50%;
+    transition: all 0.3s ease;
+}
+
+.step-dot {
+    background: #e0e0e0;
+}
+
+.step-dot-active {
+    background: #4C97FF;
+    transform: scale(1.3);
+    box-shadow: 0 0 0 4px rgba(76, 151, 255, 0.2);
+}
+
+.step-dot-completed {
+    background: #0FBD8C;
+}
+
+/* Step content */
+.step-content {
+    flex: 1;
+    overflow-y: auto;
+    padding: 2rem;
+}
+
+/* Navigation buttons */
+.button-row {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 1.5rem 2rem;
+    border-top: 2px solid #f0f0f0;
+    background: #fafafa;
+}
+
+.right-buttons {
+    display: flex;
+    gap: 1rem;
+    margin-left: auto;
+}
+
+.back-button,
+.skip-button,
+.next-button {
+    padding: 0.75rem 2rem;
+    font-size: 1rem;
+    font-weight: 600;
+    border: none;
+    border-radius: 8px;
+    cursor: pointer;
+    transition: all 0.2s ease;
+}
+
+.back-button {
+    background: transparent;
+    color: #666;
+}
+
+.back-button:hover {
+    background: #f0f0f0;
+}
+
+.skip-button {
+    background: transparent;
+    color: #999;
+    text-decoration: underline;
+}
+
+.skip-button:hover {
+    color: #666;
+}
+
+.next-button {
+    background: linear-gradient(135deg, #4C97FF 0%, #3373CC 100%);
+    color: white;
+    box-shadow: 0 4px 12px rgba(76, 151, 255, 0.3);
+}
+
+.next-button:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 6px 20px rgba(76, 151, 255, 0.4);
+}
+
+.next-button:active {
+    transform: translateY(0);
+}
\ No newline at end of file
diff --git a/src/components/welcome-modal/welcome-modal.jsx b/src/components/welcome-modal/welcome-modal.jsx
new file mode 100644
index 000000000..5b4753f3c
--- /dev/null
+++ b/src/components/welcome-modal/welcome-modal.jsx
@@ -0,0 +1,193 @@
+import bindAll from 'lodash.bindall';
+import PropTypes from 'prop-types';
+import React from 'react';
+import ReactModal from 'react-modal';
+
+import WelcomeStep from './welcome-step.jsx';
+import ThemeStep from './theme-step.jsx'; // Now connected to Redux!
+import AddonsStep from './addons-step.jsx';
+import FinalStep from './final-step.jsx';
+
+import styles from './welcome-modal.css';
+
+if (typeof document !== 'undefined') {
+    ReactModal.setAppElement('#app');
+}
+
+const WELCOME_COMPLETED_KEY = 'omniblocks:welcome_completed';
+
+export const hasCompletedWelcome = () => {
+    try {
+        return localStorage.getItem(WELCOME_COMPLETED_KEY) === 'true';
+    } catch (e) {
+        return true;
+    }
+};
+
+export const markWelcomeComplete = () => {
+    try {
+        localStorage.setItem(WELCOME_COMPLETED_KEY, 'true');
+    } catch (e) {
+        // ignore
+    }
+};
+
+class WelcomeModal extends React.Component {
+    constructor (props) {
+        super(props);
+        console.log('🎉 WelcomeModal constructor called!');
+        bindAll(this, [
+            'handleNext',
+            'handleBack',
+            'handleFinish',
+            'handleSkip'
+        ]);
+        
+        this.state = {
+            currentStep: 0
+        };
+        
+        // Define all steps - easy to add more later!
+        this.steps = [
+            {
+                id: 'welcome',
+                component: WelcomeStep,
+                skippable: false
+            },
+            {
+                id: 'theme',
+                component: ThemeStep,
+                skippable: false
+            },
+            {
+                id: 'addons',
+                component: AddonsStep,
+                skippable: true
+            },
+            {
+                id: 'final',
+                component: FinalStep,
+                skippable: false
+            }
+            // Add analytics step here later:
+            // {
+            //     id: 'analytics',
+            //     component: AnalyticsStep,
+            //     skippable: false
+            // }
+        ];
+    }
+
+    handleNext () {
+        if (this.state.currentStep < this.steps.length - 1) {
+            this.setState({currentStep: this.state.currentStep + 1});
+        } else {
+            this.handleFinish();
+        }
+    }
+
+    handleBack () {
+        if (this.state.currentStep > 0) {
+            this.setState({currentStep: this.state.currentStep - 1});
+        }
+    }
+
+    handleSkip () {
+        // Skip directly to next step
+        this.handleNext();
+    }
+
+    handleFinish () {
+        markWelcomeComplete();
+        if (this.props.onRequestClose) {
+            this.props.onRequestClose();
+        }
+    }
+
+    render () {
+        const currentStepConfig = this.steps[this.state.currentStep];
+        const CurrentStepComponent = currentStepConfig.component;
+        const isSkippable = currentStepConfig.skippable;
+        const isFirstStep = this.state.currentStep === 0;
+        const isLastStep = this.state.currentStep === this.steps.length - 1;
+
+        return (
+            <ReactModal
+                isOpen
+                className={styles.modalContent}
+                contentLabel="Welcome to OmniBlocks"
+                overlayClassName={styles.modalOverlay}
+                onRequestClose={null} // Disable closing by clicking outside
+                shouldCloseOnOverlayClick={false}
+            >
+                <div className={styles.container}>
+                    {/* Step indicator dots */}
+                    <div className={styles.stepIndicator}>
+                        {this.steps.map((step, index) => (
+                            <div
+                                key={step.id}
+                                className={
+                                    index === this.state.currentStep ?
+                                        styles.stepDotActive :
+                                        (index < this.state.currentStep ?
+                                            styles.stepDotCompleted :
+                                            styles.stepDot)
+                                }
+                            />
+                        ))}
+                    </div>
+
+                    {/* Current step content */}
+                    <div className={styles.stepContent}>
+                        <CurrentStepComponent
+                            onNext={this.handleNext}
+                            onBack={this.handleBack}
+                            onSkip={this.handleSkip}
+                            onFinish={this.handleFinish}
+                            isFirstStep={isFirstStep}
+                            isLastStep={isLastStep}
+                            {...this.props}
+                        />
+                    </div>
+
+                    {/* Navigation buttons */}
+                    <div className={styles.buttonRow}>
+                        {!isFirstStep && (
+                            <button
+                                className={styles.backButton}
+                                onClick={this.handleBack}
+                            >
+                                ← Back
+                            </button>
+                        )}
+                        
+                        <div className={styles.rightButtons}>
+                            {isSkippable && (
+                                <button
+                                    className={styles.skipButton}
+                                    onClick={this.handleSkip}
+                                >
+                                    Skip
+                                </button>
+                            )}
+
+                            <button
+                                className={styles.nextButton}
+                                onClick={isLastStep ? this.handleFinish : this.handleNext}
+                            >
+                                {isLastStep ? "Let's Go! 🚀" : 'Next →'}
+                            </button>
+                        </div>
+                    </div>
+                </div>
+            </ReactModal>
+        );
+    }
+}
+
+WelcomeModal.propTypes = {
+    onRequestClose: PropTypes.func
+    // Removed onThemeChange and onAccentColorChange - handled by Redux now!
+};
+
+export default WelcomeModal;
\ No newline at end of file
diff --git a/src/components/welcome-modal/welcome-step.css b/src/components/welcome-modal/welcome-step.css
new file mode 100644
index 000000000..a4a21ae4c
--- /dev/null
+++ b/src/components/welcome-modal/welcome-step.css
@@ -0,0 +1,89 @@
+.welcome-step {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    height: 100%;
+    text-align: center;
+}
+
+.illustration-container {
+    flex: 0 0 auto;
+    margin-bottom: 2rem;
+}
+
+.illustration-placeholder {
+    font-size: 4rem;
+    padding: 2rem;
+    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    border-radius: 16px;
+    color: white;
+}
+
+.content {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+}
+
+.title {
+    font-size: 3rem;
+    font-weight: 900;
+    margin: 0 0 1rem 0;
+    line-height: 1.2;
+    color: #333;
+}
+
+.highlight {
+    background: linear-gradient(135deg, #4C97FF 0%, #3373CC 100%);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+}
+
+.subtitle {
+    font-size: 1.25rem;
+    color: #666;
+    margin: 0 0 3rem 0;
+    line-height: 1.6;
+}
+
+.features {
+    display: flex;
+    gap: 2rem;
+    justify-content: center;
+    flex-wrap: wrap;
+    max-width: 700px;
+    margin: 0 auto;
+}
+
+.feature {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    padding: 1rem;
+    background: #f8f9fa;
+    border-radius: 12px;
+    text-align: left;
+    flex: 1;
+    min-width: 180px;
+}
+
+.icon {
+    font-size: 2.5rem;
+    flex-shrink: 0;
+}
+
+.feature-text h3 {
+    margin: 0 0 0.25rem 0;
+    font-size: 1rem;
+    font-weight: 700;
+    color: #333;
+}
+
+.feature-text p {
+    margin: 0;
+    font-size: 0.875rem;
+    color: #666;
+}
\ No newline at end of file
diff --git a/src/components/welcome-modal/welcome-step.jsx b/src/components/welcome-modal/welcome-step.jsx
new file mode 100644
index 000000000..451b7ad79
--- /dev/null
+++ b/src/components/welcome-modal/welcome-step.jsx
@@ -0,0 +1,58 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import styles from './welcome-step.css';
+
+const WelcomeStep = () => (
+    <div className={styles.welcomeStep}>
+        <div className={styles.illustrationContainer}>
+            {/* Your SVG illustration goes here! */}
+            <div className={styles.illustrationPlaceholder}>
+                🎨 Your awesome SVG illustration here!
+            </div>
+        </div>
+
+        <div className={styles.content}>
+            <h1 className={styles.title}>
+                Welcome to <span className={styles.highlight}>OmniBlocks</span>! 🎉
+            </h1>
+            
+            <p className={styles.subtitle}>
+                Let's set up your perfect creative environment in just a few quick steps!
+            </p>
+
+            <div className={styles.features}>
+                <div className={styles.feature}>
+                    <span className={styles.icon}>⚡</span>
+                    <div className={styles.featureText}>
+                        <h3>Lightning Fast</h3>
+                        <p>Optimized for the best performance</p>
+                    </div>
+                </div>
+                
+                <div className={styles.feature}>
+                    <span className={styles.icon}>🎨</span>
+                    <div className={styles.featureText}>
+                        <h3>Fully Customizable</h3>
+                        <p>Make it your own with themes and addons</p>
+                    </div>
+                </div>
+                
+                <div className={styles.feature}>
+                    <span className={styles.icon}>🚀</span>
+                    <div className={styles.featureText}>
+                        <h3>Powerful Features</h3>
+                        <p>Everything you need to create amazing projects</p>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+);
+
+WelcomeStep.propTypes = {
+    onNext: PropTypes.func,
+    isFirstStep: PropTypes.bool,
+    isLastStep: PropTypes.bool
+};
+
+export default WelcomeStep;
\ No newline at end of file
diff --git a/src/containers/gui.jsx b/src/containers/gui.jsx
index d20dd26dd..08be5fb1b 100644
--- a/src/containers/gui.jsx
+++ b/src/containers/gui.jsx
@@ -5,7 +5,7 @@ import {connect} from 'react-redux';
 import ReactModal from 'react-modal';
 import VM from 'scratch-vm';
 import {injectIntl, intlShape} from 'react-intl';
-
+import {hasCompletedWelcome} from '../components/welcome-modal/welcome-modal.jsx';
 import ErrorBoundaryHOC from '../lib/error-boundary-hoc.jsx';
 import {
     getIsError,
@@ -149,6 +149,8 @@ GUI.defaultProps = {
 };
 
 const mapStateToProps = state => {
+    const showWelcomeModal = !hasCompletedWelcome();
+    console.log('🔗 Container showWelcomeModal:', showWelcomeModal);
     const loadingState = state.scratchGui.projectState.loadingState;
     return {
         activeTabIndex: state.scratchGui.editorTab.activeTabIndex,
@@ -162,6 +164,7 @@ const mapStateToProps = state => {
         error: state.scratchGui.projectState.error,
         isError: getIsError(loadingState),
         isEmbedded: state.scratchGui.mode.isEmbedded,
+        showWelcomeModal: !hasCompletedWelcome(),
         isFullScreen: state.scratchGui.mode.isFullScreen || state.scratchGui.mode.isEmbedded,
         isPlayerOnly: state.scratchGui.mode.isPlayerOnly,
         isRtl: state.locales.isRtl,
@@ -194,7 +197,9 @@ const mapDispatchToProps = dispatch => ({
     onActivateSongsTab: () => dispatch(activateTab(SONGS_TAB_INDEX)),
     onRequestCloseBackdropLibrary: () => dispatch(closeBackdropLibrary()),
     onRequestCloseCostumeLibrary: () => dispatch(closeCostumeLibrary()),
+    onRequestCloseWelcomeModal: () => {},
     onRequestCloseTelemetryModal: () => dispatch(closeTelemetryModal())
+    
 });
 
 const ConnectedGUI = injectIntl(connect(

From 46d7d3ac635d0bfeb21193c6d60e1786a9af282c Mon Sep 17 00:00:00 2001
From: supervoidcoder <88671013+supervoidcoder@users.noreply.github.com>
Date: Tue, 2 Dec 2025 00:36:28 +0000
Subject: [PATCH 2/7] fix: well it's not a fix if it doesn't fix anything but
 it's a TRY to fix

---
 src/components/gui/gui.jsx | 2 ++
 src/containers/gui.jsx     | 1 +
 2 files changed, 3 insertions(+)

diff --git a/src/components/gui/gui.jsx b/src/components/gui/gui.jsx
index daff0481a..bda44fbcd 100644
--- a/src/components/gui/gui.jsx
+++ b/src/components/gui/gui.jsx
@@ -598,7 +598,9 @@ const mapStateToProps = state => ({
     // This is the button's mode, as opposed to the actual current state
     blocksId: state.scratchGui.timeTravel.year.toString(),
     stageSizeMode: state.scratchGui.stageSize.stageSize,
+    showWelcomeModal: !hasCompletedWelcome(),
     theme: state.scratchGui.theme.theme
+
 });
 
 export default injectIntl(connect(
diff --git a/src/containers/gui.jsx b/src/containers/gui.jsx
index 08be5fb1b..d4970f07e 100644
--- a/src/containers/gui.jsx
+++ b/src/containers/gui.jsx
@@ -37,6 +37,7 @@ import vmListenerHOC from '../lib/vm-listener-hoc.jsx';
 import vmManagerHOC from '../lib/vm-manager-hoc.jsx';
 import cloudManagerHOC from '../lib/cloud-manager-hoc.jsx';
 
+
 import GUIComponent from '../components/gui/gui.jsx';
 import {setIsScratchDesktop} from '../lib/isScratchDesktop.js';
 import TWFullScreenResizerHOC from '../lib/tw-fullscreen-resizer-hoc.jsx';

From 81bead73f55cf67dc6437d067b60f18b7a087fc9 Mon Sep 17 00:00:00 2001
From: supervoidcoder <88671013+supervoidcoder@users.noreply.github.com>
Date: Tue, 2 Dec 2025 00:55:10 +0000
Subject: [PATCH 3/7] fix: try fix

---
 src/components/gui/gui.jsx | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/components/gui/gui.jsx b/src/components/gui/gui.jsx
index bda44fbcd..ebc827ce1 100644
--- a/src/components/gui/gui.jsx
+++ b/src/components/gui/gui.jsx
@@ -8,7 +8,6 @@ import MediaQuery from 'react-responsive';
 import {Tab, Tabs, TabList, TabPanel} from 'react-tabs';
 import tabStyles from 'react-tabs/style/react-tabs.css';
 import VM from 'scratch-vm';
-import WelcomeModal from '../welcome-modal/welcome-modal.jsx';
 import Blocks from '../../containers/blocks.jsx';
 import CostumeTab from '../../containers/costume-tab.jsx';
 import TargetPane from '../../containers/target-pane.jsx';
@@ -598,7 +597,6 @@ const mapStateToProps = state => ({
     // This is the button's mode, as opposed to the actual current state
     blocksId: state.scratchGui.timeTravel.year.toString(),
     stageSizeMode: state.scratchGui.stageSize.stageSize,
-    showWelcomeModal: !hasCompletedWelcome(),
     theme: state.scratchGui.theme.theme
 
 });

From a588c356ef151d8095fe7b91001209565a5ab905 Mon Sep 17 00:00:00 2001
From: supervoidcoder <88671013+supervoidcoder@users.noreply.github.com>
Date: Tue, 2 Dec 2025 01:00:43 +0000
Subject: [PATCH 4/7] bleh

---
 src/components/gui/gui.jsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/gui/gui.jsx b/src/components/gui/gui.jsx
index ebc827ce1..f5ed8e943 100644
--- a/src/components/gui/gui.jsx
+++ b/src/components/gui/gui.jsx
@@ -36,7 +36,7 @@ import TWRestorePointManager from '../../containers/tw-restore-point-manager.jsx
 import TWFontsModal from '../../containers/tw-fonts-modal.jsx';
 import TWUnknownPlatformModal from '../../containers/tw-unknown-platform-modal.jsx';
 import TWInvalidProjectModal from '../../containers/tw-invalid-project-modal.jsx';
-
+import WelcomeModal from '../welcome-modal/welcome-modal.jsx';
 import {STAGE_SIZE_MODES, FIXED_WIDTH, UNCONSTRAINED_NON_STAGE_WIDTH} from '../../lib/layout-constants';
 import {resolveStageSize} from '../../lib/screen-utils';
 import {Theme} from '../../lib/themes';

From 09b101e3f32b860e17c5d57bbde97da11580f67c Mon Sep 17 00:00:00 2001
From: supervoidcoder <88671013+supervoidcoder@users.noreply.github.com>
Date: Tue, 2 Dec 2025 01:15:08 +0000
Subject: [PATCH 5/7] w

---
 src/components/welcome-modal/welcome-modal.jsx | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/components/welcome-modal/welcome-modal.jsx b/src/components/welcome-modal/welcome-modal.jsx
index 5b4753f3c..e71008305 100644
--- a/src/components/welcome-modal/welcome-modal.jsx
+++ b/src/components/welcome-modal/welcome-modal.jsx
@@ -10,9 +10,7 @@ import FinalStep from './final-step.jsx';
 
 import styles from './welcome-modal.css';
 
-if (typeof document !== 'undefined') {
-    ReactModal.setAppElement('#app');
-}
+
 
 const WELCOME_COMPLETED_KEY = 'omniblocks:welcome_completed';
 
@@ -36,6 +34,9 @@ class WelcomeModal extends React.Component {
     constructor (props) {
         super(props);
         console.log('🎉 WelcomeModal constructor called!');
+         if (typeof document !== 'undefined') {
+            ReactModal.setAppElement('#app');
+        }
         bindAll(this, [
             'handleNext',
             'handleBack',

From a17207e83428b0cd8a7717ec9bab771a38c24d33 Mon Sep 17 00:00:00 2001
From: supervoidcoder <88671013+supervoidcoder@users.noreply.github.com>
Date: Tue, 2 Dec 2025 01:19:38 +0000
Subject: [PATCH 6/7] debug

---
 src/components/gui/gui.jsx | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/src/components/gui/gui.jsx b/src/components/gui/gui.jsx
index f5ed8e943..661e42342 100644
--- a/src/components/gui/gui.jsx
+++ b/src/components/gui/gui.jsx
@@ -239,10 +239,15 @@ const GUIComponent = props => {
                 {...componentProps}
             >
                 {alwaysEnabledModals}
-                {showWelcomeModal ? (
-                <WelcomeModal
-                    onRequestClose={onRequestCloseWelcomeModal} />
-                    ) : null}
+                {showWelcomeModal ? (() => {
+    console.log('🚨 About to render WelcomeModal!');
+    console.log('🚨 WelcomeModal is:', WelcomeModal);
+    console.log('🚨 WelcomeModal typeof:', typeof WelcomeModal);
+    return (
+        <WelcomeModal
+            onRequestClose={onRequestCloseWelcomeModal} />
+    );
+})() : null}
                 {telemetryModalVisible ? (
                     <TelemetryModal
                         isRtl={isRtl}

From aed74362c6a7746a9fd1e694adf656a3a48918be Mon Sep 17 00:00:00 2001
From: supervoidcoder <88671013+supervoidcoder@users.noreply.github.com>
Date: Tue, 2 Dec 2025 01:25:32 +0000
Subject: [PATCH 7/7] ugh

---
 src/components/gui/gui.jsx | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/src/components/gui/gui.jsx b/src/components/gui/gui.jsx
index 661e42342..c1c8d823e 100644
--- a/src/components/gui/gui.jsx
+++ b/src/components/gui/gui.jsx
@@ -160,10 +160,14 @@ const GUIComponent = props => {
         unknownPlatformModalVisible,
         invalidProjectModalVisible,
         showWelcomeModal,
+        onRequestCloseWelcomeModal,
         vm,
         ...componentProps
     } = omit(props, 'dispatch');
     console.log('🎯 showWelcomeModal:', showWelcomeModal);
+        const welcomeModalElement = showWelcomeModal ? (
+        <WelcomeModal onRequestClose={onRequestCloseWelcomeModal} />
+    ) : null;
     if (children) {
         return <Box {...componentProps}>{children}</Box>;
     }
@@ -239,15 +243,7 @@ const GUIComponent = props => {
                 {...componentProps}
             >
                 {alwaysEnabledModals}
-                {showWelcomeModal ? (() => {
-    console.log('🚨 About to render WelcomeModal!');
-    console.log('🚨 WelcomeModal is:', WelcomeModal);
-    console.log('🚨 WelcomeModal typeof:', typeof WelcomeModal);
-    return (
-        <WelcomeModal
-            onRequestClose={onRequestCloseWelcomeModal} />
-    );
-})() : null}
+               
                 {telemetryModalVisible ? (
                     <TelemetryModal
                         isRtl={isRtl}