Add interactive tutorial wizard for first-time onboarding

- TutorialWizard: Portal-based card with gradient background, step navigation,
  "Show on startup" checkbox, and per-step marker highlighting (circle/rect)
- Marker tracks target UI elements via ResizeObserver with proper cleanup
- tutorialEnabled setting in IUISettings + SettingsDialog checkbox
- Integrates after app init, before loading last score from localStorage;
  auto-expands/collapses mixer panel on relevant steps
- Grid now forwards data-* attributes for tutorial target selectors
- E2E: storage-state.json disables tutorial during Playwright tests
- 12 unit tests covering navigation, marker positioning, and observer lifecycle

Signed-off-by: Mike Lischke <mike@lischke-online.de>

Author: mike-lischke

cspell.json

@@ -109,6 +109,7 @@
         "tableholder",
         "testadmin",
         "testpass",
+        "topbar",
         "wavesurfer",
         "xlink"
     ],

playwright.config.ts

@@ -15,6 +15,7 @@ export default defineConfig({
         trace: "on-first-retry",
         screenshot: "only-on-failure",
         video: "retain-on-failure",
+        storageState: "tests/e2e/storage-state.json",
     },
     webServer: {
         command: process.env.CI ? "npm run serve:e2e" : "npm run build && npm run serve:e2e",

src/App.tsx

@@ -67,8 +67,10 @@ import { ModeManager } from "./ui/ModeManager.js";
 import { MouseHandler } from "./ui/MouseHandler.js";
 import { SelectionManager } from "./ui/SelectionManager.js";
 import { SettingsDialog } from "./ui/SettingsDialog.js";
+import { TutorialWizard } from "./ui/TutorialWizard.js";
 import { UserGroupEditor } from "./ui/UserGroupEditor.js";
 import { PermissionEditor } from "./ui/PermissionEditor.js";
+import { tutorialSteps, mixerStepIndex } from "./core/TutorialSteps.js";
 
 const ScoreLibrary = lazy(() => {
     return import("./ui/ScoreLibrary.js").then((m) => {
@@ -123,6 +125,7 @@ export class App extends UIComponent<{}, IAppState> {
     private userGroupEditorRef = createRef<UserGroupEditor>();
     private permissionEditorRef = createRef<PermissionEditor>();
     private printDialogRef = createRef<PrintDialog>();
+    private tutorialWizardRef = createRef<TutorialWizard>();
     private valueDialogRef = createRef<ValueDialog>();
     private confirmDialogRef = createRef<ConfirmDialog>();
 
@@ -146,6 +149,8 @@ export class App extends UIComponent<{}, IAppState> {
     private statsItem?: IStatusBarItem;
     private notificationItem?: IStatusBarItem;
 
+    private currentTutorialStep = 0;
+
     public constructor(props: {}) {
         super(props);
 
@@ -366,6 +371,7 @@ export class App extends UIComponent<{}, IAppState> {
                                                         imageOnly
                                                         className="du-btn-ghost"
                                                         data-tooltip="Display Options"
+                                                        data-tutorial="display-options"
                                                         onClick={this.handleDisplayOptionsClick}
                                                     >
                                                         <Icon
@@ -378,6 +384,7 @@ export class App extends UIComponent<{}, IAppState> {
                                                         imageOnly
                                                         className="du-btn-ghost"
                                                         data-tooltip="Score Library"
+                                                        data-tutorial="score-library"
                                                         onClick={this.handleScoreLibraryClick}
                                                     >
                                                         <Icon
@@ -391,6 +398,7 @@ export class App extends UIComponent<{}, IAppState> {
                                                         imageOnly
                                                         className="du-btn-ghost"
                                                         data-tooltip="Print / Export to PDF"
+                                                        data-tutorial="print"
                                                         onClick={this.handlePrintClick}
                                                     >
                                                         <Icon
@@ -441,6 +449,7 @@ export class App extends UIComponent<{}, IAppState> {
                                                     dataModel={this.dataModel}
                                                     services={this.services}
                                                     undoManager={this.undoManager!}
+                                                    data-tutorial="playback"
                                                 />
                                                 <Container
                                                     id="arrangementPalette"
@@ -489,6 +498,14 @@ export class App extends UIComponent<{}, IAppState> {
                         <TooltipProvider />
                         <ValueDialog ref={this.valueDialogRef} />
                         <SettingsDialog ref={this.settingsDialogRef} />
+                        <TutorialWizard
+                            ref={this.tutorialWizardRef}
+                            steps={tutorialSteps}
+                            tutorialEnabled={AppStorage.loadUISettings()?.tutorialEnabled ?? true}
+                            onTutorialEnabledChange={this.handleTutorialEnabledChange}
+                            onStepChange={this.handleTutorialStepChange}
+                            onClose={this.handleTutorialClose}
+                        />
                         <BackendDisconnectedDialog
                             ref={this.backendDisconnectedDialogRef}
                             onReconnected={() => {
@@ -819,6 +836,25 @@ export class App extends UIComponent<{}, IAppState> {
 
         const params = new URL(window.location.href).searchParams;
         const hasBananaDrum = params.has("a") || params.has("a2");
+        const hasScoreParam = params.has("score");
+
+        const showTutorial = !hasBananaDrum && !hasScoreParam
+            && (AppStorage.loadUISettings()?.tutorialEnabled ?? true);
+
+        if (showTutorial) {
+            this.initAppState();
+            this.setState({ phase: AppPhase.Running }, () => {
+                this.tutorialWizardRef.current?.open();
+            });
+
+            return;
+        }
+
+        await this.loadInitialScore(params);
+    }
+
+    private async loadInitialScore(params: URLSearchParams): Promise<void> {
+        const hasBananaDrum = params.has("a") || params.has("a2");
 
         let pendingWarning: string | undefined;
 
@@ -862,6 +898,40 @@ export class App extends UIComponent<{}, IAppState> {
         });
     }
 
+    private handleTutorialClose = (completed: boolean): void => {
+        this.tutorialWizardRef.current?.close(completed);
+        this.loadScorebook(undefined);
+    };
+
+    private handleTutorialStepChange = (stepIndex: number): void => {
+        const prevStep = this.currentTutorialStep;
+        this.currentTutorialStep = stepIndex;
+
+        if (stepIndex === mixerStepIndex) {
+            this.toggleMixerIf(!this.isMixerExpanded());
+        }
+
+        if (prevStep === mixerStepIndex && stepIndex !== mixerStepIndex) {
+            this.toggleMixerIf(this.isMixerExpanded());
+        }
+    };
+
+    private isMixerExpanded(): boolean {
+        return document.querySelector(".trackControlsList")?.classList.contains("expanded") ?? false;
+    }
+
+    private toggleMixerIf(condition: boolean): void {
+        if (!condition) {
+            return;
+        }
+
+        document.querySelector<HTMLElement>(".trackControlsToggle")?.click();
+    }
+
+    private handleTutorialEnabledChange = (enabled: boolean): void => {
+        AppStorage.saveSetting("tutorialEnabled", enabled);
+    };
+
     private handleGithubClick = () => {
         window.open("https://github.com/mike-lischke/animada-score-book", "_blank");
     };
@@ -1317,7 +1387,12 @@ export class App extends UIComponent<{}, IAppState> {
         return true;
     };
 
-    private loadScorebook(source?: URLSearchParams | ISbDmScore) {
+    private initAppState(): void {
+        this.undoManager = new UndoManager(this.dataModel);
+        this.arrangementPlayer = new ArrangementPlayer(this.dataModel);
+    }
+
+    private loadScorebook(source?: IArrangementSnapshot | URLSearchParams | ISbDmScore) {
         let resolvedSource: IArrangementSnapshot | URLSearchParams | ISbDmScore | undefined;
 
         if (source) {
@@ -1362,7 +1437,8 @@ export class App extends UIComponent<{}, IAppState> {
             document.title = arrangement.title + " - Animada Score Book";
         }
 
-        AppStorage.saveSetting("currentScore", stringifyPackedArrangement((arrangement as Arrangement).toSnapshot()),
+        AppStorage.saveSetting("currentScore",
+            stringifyPackedArrangement((arrangement as Arrangement).toSnapshot()),
         );
 
         this.forceUpdate();

src/components/ui/Arrangement/ArrangementPlayControls.tsx

@@ -130,7 +130,7 @@ export class ArrangementPlayControls
         const arrangementView = dataModel.arrangement!;
 
         return (
-            <Grid id="arrangementPlayControls" columns={[160, "auto"]}>
+            <Grid id="arrangementPlayControls" columns={[160, "auto"]} {...this.dataAttributes}>
                 <Container
                     orientation={Orientation.TopDown}
                     mainAlignment={ChildAlignment.Start}

src/components/ui/Arrangement/TrackControls.tsx

@@ -165,7 +165,12 @@ export class TrackControls extends UIComponent<ITrackControlsProperties, ITrackC
         });
 
         return (
-            <Container innerRef={innerRef} className={listClassName} orientation={Orientation.TopDown}>
+            <Container
+                innerRef={innerRef}
+                className={listClassName}
+                orientation={Orientation.TopDown}
+                data-tutorial="mixer"
+            >
                 <Container className="trackControlsHeader" crossAlignment={ChildAlignment.Center}>
                     <Button
                         className="trackControlsToggle"

src/components/ui/framework/Button.tsx

@@ -60,7 +60,7 @@ export class Button extends UIComponent<IButtonProperties> {
             this.classFromProperty(round, "du-btn-circle"),
             this.classFromProperty(imageOnly, "imageOnly"),
             this.classFromProperty(disabled, "du-btn-disabled"),
-            this.classFromProperty(isDefault, "default"),
+            this.classFromProperty(isDefault, "du-btn-primary"),
         ]);
 
         const content = children ?? caption;

src/components/ui/framework/Grid.tsx

@@ -59,6 +59,7 @@ export class Grid extends UIComponent<IGridProperties> {
                 ref={innerRef as preact.RefObject<HTMLDivElement>}
                 className={className}
                 style={newStyle}
+                {...this.dataAttributes}
             >
                 {children}
             </div>

src/components/ui/framework/Popup.tsx

@@ -31,8 +31,11 @@ interface IPopupProperties extends IPortalProperties {
 }
 
 interface IPopupState {
-    hidden: boolean;         // Used to temporarily hide the popup on scroll.
-    currentTarget?: DOMRect; // The area for placement computation.
+    /** Used to temporarily hide the popup on scroll. */
+    hidden: boolean;
+
+    /** The area for placement computation. */
+    currentTarget?: DOMRect;
 }
 
 /**

src/core/AppStorage.ts

@@ -63,6 +63,9 @@ export interface IUISettings {
 
     /** Whether to show the permission matrix in the Score Library tree. Defaults to true. */
     showPermMatrix?: boolean;
+
+    /** Whether to show the tutorial wizard on app startup. Defaults to true. */
+    tutorialEnabled?: boolean;
 }
 
 /**

src/core/TutorialSteps.ts

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) Mike Lischke. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ */
+
+export interface ITutorialStep {
+    title: string;
+    description: string;
+    targetSelector?: string;
+    markerShape?: "circle" | "rect";
+}
+
+/** Index of the Mixer step in {@link tutorialSteps}. */
+export const mixerStepIndex = 4;
+
+export const tutorialSteps: ITutorialStep[] = [
+    {
+        title: "Welcome",
+        description: "Animada Score Book helps you create, arrange, and share samba arrangements."
+            + " This tutorial walks you through the most important features.",
+    },
+    {
+        title: "Score Library",
+        targetSelector: "[data-tutorial=\"score-library\"]",
+        markerShape: "circle",
+        description: "The Score Library gives you an overview of all your saved arrangements."
+            + " Click the library icon to open it."
+            + " From here you can load scores, create folders, and import new arrangements.",
+    },
+    {
+        title: "Display Options",
+        targetSelector: "[data-tutorial=\"display-options\"]",
+        markerShape: "circle",
+        description: "Click the gear icon to open display options: theme, zoom level, and other settings."
+            + " Choose between various light and dark themes.",
+    },
+    {
+        title: "Playback",
+        targetSelector: "[data-tutorial=\"playback\"]",
+        markerShape: "rect",
+        description: "Press the play button to start playback. You can select a range of measures"
+            + " to play only that section. Loop, count-in, and metronome controls"
+            + " are always visible in the playback bar.",
+    },
+    {
+        title: "Mixer",
+        targetSelector: "[data-tutorial=\"mixer\"]",
+        markerShape: "rect",
+        description: "On the left side you'll find the mixer with volume controls for each track."
+            + " Drag the slider left to lower the volume, or right for a focus boost."
+            + " This lets you set the perfect balance for your ensemble.",
+    },
+    {
+        title: "Print / PDF",
+        targetSelector: "[data-tutorial=\"print\"]",
+        markerShape: "circle",
+        description: "Click the PDF icon to open the print dialog. Choose how many bars per line"
+            + " and which tracks to include."
+            + " You can print the arrangement directly or save it as a PDF.",
+    },
+    {
+        title: "MP3 Export",
+        targetSelector: "#recordButton",
+        markerShape: "circle",
+        description: "Click the record button to export your arrangement as an MP3 file."
+            + " The app renders the full arrangement with all instruments"
+            + " and gives you an MP3 file to download.",
+    },
+    {
+        title: "You're ready!",
+        description: "That's it! You can re-enable the tutorial anytime in Display Options."
+            + " Have fun with Animada Score Book!",
+    },
+];