feat: Add Interactive First Project Tutorial with Step Validation

[Ashutoshx7]

Summary

This PR introduces an interactive step-by-step tutorial that guides new users through creating their first Music Blocks project. Unlike the existing static help tour where users simply click through slides, this tutorial validates user actions and only allows progression when each step is completed.

Problem

New users often struggle with Music Blocks' learning curve:

• They don't understand the block-based programming paradigm
• They can't find where to start
• They get overwhelmed by the many palettes and options
• The existing help tour shows information but doesn't ensure users actually perform the actions

Solution

An interactive tutorial system featuring:

• 10 guided steps - From finding the Start block to playing your first melody
• Action validation - The "Next" button only enables when the user completes the required action
• Visual highlighting - Spotlight effect focuses attention on the relevant UI element
• Real-time feedback - Status indicators show pending (⏳) vs completed (✅) actions
• Smart overlay - Reduced opacity during drag-and-drop steps to allow full canvas/palette interaction

Tutorial Steps

Step	Task	Validation
1	Find the Start Block	Auto-complete (observation)
2	Open Rhythm Palette	Detects palette is open
3	Drag a Note Block	Counts new blocks on canvas
4	Connect Note to Start	Checks block connections
5	Press Play	Detects play button click
6	Open Pitch Palette	Detects palette is open
7	Add Pitch to Note	Traverses block hierarchy
8	Play Again	Detects play button click
9	Add More Notes	Optional, auto-complete
10	Congratulations	Tutorial complete

Changes

New Files

• js/tutorial/FirstProjectTutorial.js - The main interactive tutorial class

Modified Files

• js/widgets/help.js - Added "Start Interactive Tutorial" button
• js/turtledefs.js - Added tutorial introduction cards to HELPCONTENT
• js/activity.js - Added tutorial initialization
• index.html - Added script reference

Technical Highlights

• Validator Architecture: Each step has a validator function that checks if the user completed the action
• Connection Traversal: The pitch-in-note validator traverses the entire block hierarchy
• Interaction Mode: Steps requiring drag-and-drop use reduced overlay opacity (20%) to allow free interaction

Testing

• All 10 steps complete successfully
• Validators correctly detect user actions
• Overlay allows interaction for drag-and-drop steps
• Tutorial can be closed at any time
• Back button works correctly

How to Test

1. Open Music Blocks
2. Click the Help button (?)
3. Navigate to "Build Your First Project" card
4. Click "🚀 Start Interactive Tutorial"
5. Follow the 10 steps to create your first project

cursorful-video-1768044942838.mp4

• Feature

[github-actions]

✅ All Jest tests passed! This PR is ready to merge.

[github-actions]

✅ All Jest tests passed! This PR is ready to merge.

[github-actions]

✅ All Jest tests passed! This PR is ready to merge.

[Ashutoshx7]

@walterbender @pikurasa

In our last meeting, we discussed the possibility of adding a guided tutorial.
Based on that discussion, I’ve added a new card that serves as the entry point for this guided tutorial.

I’d really appreciate your feedback on this approach and whether this direction aligns with what we had in mind.

Thanks!

[walterbender]

I think the idea of this. Maybe we can get broader feedback from @pikurasa and others.

I did encounter a few issues, such as the palette closing then I clicked next in the tutorial (after I opened the Rhythm palette). And if froze on Card 4.

If we do do this, maybe it should appear sooner in the help card sequence.

[Inuth0603]

Hey @Ashutoshx7, this interactive tutorial is looking great! 🎵

I pulled the branch locally to dig into the issues @walterbender mentioned and found a couple of things that might help fix them:

1. Step 5 Freeze (Play Button)
   I think the onclick assignment here is conflicting with the main app's internal listeners, which causes the tutorial to miss the click. I switched it to addEventListener locally and it fixed the freeze completely:

   // In _setupPlayListener()
   playBtn.addEventListener("click", () => {
   this._playPressed = true;
   }, { once: true });

2. Freezing on Step 4 (Connect to Start)
   Regarding the crash Walter saw when the palette closes unexpectedly—the validator seems to error out if it tries to check connections on a block that isn't fully ready or found. Adding a safety check in _isBlockConnectedToStart to make sure startBlock exists before checking its connections should prevent that crash.

3. Header Text Overlap
   Just a small visual catch: the title text on Step 1 ("Tutorial Step 1 of 10...") and a few others is a bit big and overlaps the close button/layout on some screen sizes. Maybe slightly reducing the font-size for the modal headers would clean that up?

Hope this helps get it merged! Happy to test again whenever you update. 🚀

[github-actions]

✅ All Jest tests passed! This PR is ready to merge.

[github-actions]

✅ All Jest tests passed! This PR is ready to merge.

[Ashutoshx7]

@walterbender
addressed the issues you pointed out and pushed the fixes.
I’ve also attached a short recording to show the updated behavior; would appreciate a quick look when you get a chance.

Screen.Recording.2026-02-01.041809.mp4

this pr is ready for review

[walterbender]

Generally looks good. But maybe @pikurasa and I can sit down with you to go over the details of the script. For example, should we impose a starting condition? Maybe the goal should include an action block?

[github-actions]

✅ All Jest tests passed! This PR is ready to merge.

[walterbender]

I really like where this is going. Still some rough spots. For example, in several cases, you are asked to drag something from a palette when the palette is closed.

Also, I am happy to see the launch tutorial in the help but it should be near the beginning on its own card. It is not really discoverable where it is.

[vanshika2720]

@Ashutoshx7 ESLint failing.. and also resolve merge conflicts.

[github-actions]

✅ All Jest tests passed! This PR is ready to merge.

[github-actions]

❌ Some Jest tests failed. Please check the logs and fix the issues before merging.

Failed Tests:

activity_context_regression.test.js

[github-actions]

❌ Some Jest tests failed. Please check the logs and fix the issues before merging.

Failed Tests:

activity_context_regression.test.js

[github-actions]

✅ All Jest tests passed! This PR is ready to merge.

[github-actions]

✅ All Jest tests passed! This PR is ready to merge.

[github-actions]

This PR has merge conflicts with master.

Please rebase your branch:

# Add upstream remote (one-time setup)
git remote add upstream https://github.com/sugarlabs/musicblocks.git

# Fetch latest master and rebase
git fetch upstream
git rebase upstream/master

# Resolve any conflicts, then:
git push --force-with-lease origin YOUR_BRANCH

Tip: Enable "Allow edits from maintainers" on this PR so we can auto-rebase for you next time. This only grants access to your PR branch. Your fork's other branches are not affected.