From b66bab48bd31adaabe18270dc4e48e9ba4e7622c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?H=C3=B6rdle=20Bot?= <bot@hoerdle.local>
Date: Wed, 26 Nov 2025 10:13:40 +0100
Subject: [PATCH] Feat: Add Onboarding Assistant with driver.js

---
 app/page.tsx                  |   8 ++-
 components/Game.tsx           |  33 ++++++----
 components/OnboardingTour.tsx | 109 ++++++++++++++++++++++++++++++++++
 package-lock.json             |   7 +++
 package.json                  |   1 +
 5 files changed, 143 insertions(+), 15 deletions(-)
 create mode 100644 components/OnboardingTour.tsx

diff --git a/app/page.tsx b/app/page.tsx
index caa244d..7c461cd 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -1,5 +1,6 @@
 import Game from '@/components/Game';
 import NewsSection from '@/components/NewsSection';
+import OnboardingTour from '@/components/OnboardingTour';
 import { getOrCreateDailyPuzzle } from '@/lib/dailyPuzzle';
 import Link from 'next/link';
 import { PrismaClient } from '@prisma/client';
@@ -30,7 +31,7 @@ export default async function Home() {
 
   return (
     <>
-      <div style={{ textAlign: 'center', padding: '1rem', background: '#f3f4f6' }}>
+      <div id="tour-genres" style={{ textAlign: 'center', padding: '1rem', background: '#f3f4f6' }}>
         <div style={{ display: 'flex', justifyContent: 'center', gap: '1rem', flexWrap: 'wrap', alignItems: 'center' }}>
           <div className="tooltip">
             <Link href="/" style={{ fontWeight: 'bold', textDecoration: 'underline' }}>Global</Link>
@@ -95,9 +96,12 @@ export default async function Home() {
         )}
       </div>
 
-      <NewsSection />
+      <div id="tour-news">
+        <NewsSection />
+      </div>
 
       <Game dailyPuzzle={dailyPuzzle} genre={null} />
+      <OnboardingTour />
     </>
   );
 }
diff --git a/components/Game.tsx b/components/Game.tsx
index e6cba23..651e366 100644
--- a/components/Game.tsx
+++ b/components/Game.tsx
@@ -251,7 +251,7 @@ export default function Game({ dailyPuzzle, genre = null, isSpecial = false, max
     return (
         <div className="container">
             <header className="header">
-                <h1 className="title">Hördle #{dailyPuzzle.puzzleNumber}{genre ? ` / ${genre}` : ''}</h1>
+                <h1 id="tour-title" className="title">Hördle #{dailyPuzzle.puzzleNumber}{genre ? ` / ${genre}` : ''}</h1>
                 <div style={{ fontSize: '0.9rem', color: '#666', marginTop: '0.5rem', marginBottom: '1rem' }}>
                     Next puzzle in: {timeUntilNext}
                 </div>
@@ -259,22 +259,26 @@ export default function Game({ dailyPuzzle, genre = null, isSpecial = false, max
 
             <main className="game-board">
                 <div style={{ borderBottom: '1px solid #e5e7eb', paddingBottom: '1rem' }}>
-                    <div className="status-bar">
+                    <div id="tour-status" className="status-bar">
                         <span>Attempt {gameState.guesses.length + 1} / {maxAttempts}</span>
                         <span>{unlockedSeconds}s unlocked</span>
                     </div>
 
-                    <ScoreDisplay score={gameState.score} breakdown={gameState.scoreBreakdown} />
+                    <div id="tour-score">
+                        <ScoreDisplay score={gameState.score} breakdown={gameState.scoreBreakdown} />
+                    </div>
 
-                    <AudioPlayer
-                        ref={audioPlayerRef}
-                        src={dailyPuzzle.audioUrl}
-                        unlockedSeconds={unlockedSeconds}
-                        startTime={dailyPuzzle.startTime}
-                        autoPlay={lastAction === 'SKIP' || (lastAction === 'GUESS' && !hasWon && !hasLost)}
-                        onReplay={addReplay}
-                        onHasPlayedChange={setHasPlayedAudio}
-                    />
+                    <div id="tour-player">
+                        <AudioPlayer
+                            ref={audioPlayerRef}
+                            src={dailyPuzzle.audioUrl}
+                            unlockedSeconds={unlockedSeconds}
+                            startTime={dailyPuzzle.startTime}
+                            autoPlay={lastAction === 'SKIP' || (lastAction === 'GUESS' && !hasWon && !hasLost)}
+                            onReplay={addReplay}
+                            onHasPlayedChange={setHasPlayedAudio}
+                        />
+                    </div>
                 </div>
 
                 <div className="guess-list">
@@ -293,9 +297,12 @@ export default function Game({ dailyPuzzle, genre = null, isSpecial = false, max
 
                 {!hasWon && !hasLost && (
                     <>
-                        <GuessInput onGuess={handleGuess} disabled={isProcessingGuess} />
+                        <div id="tour-input">
+                            <GuessInput onGuess={handleGuess} disabled={isProcessingGuess} />
+                        </div>
                         {gameState.guesses.length < maxAttempts - 1 ? (
                             <button
+                                id="tour-controls"
                                 onClick={handleSkip}
                                 className="skip-button"
                             >
diff --git a/components/OnboardingTour.tsx b/components/OnboardingTour.tsx
new file mode 100644
index 0000000..473c301
--- /dev/null
+++ b/components/OnboardingTour.tsx
@@ -0,0 +1,109 @@
+'use client';
+
+import { useEffect } from 'react';
+import { driver } from 'driver.js';
+import 'driver.js/dist/driver.css';
+
+export default function OnboardingTour() {
+    useEffect(() => {
+        const hasCompletedOnboarding = localStorage.getItem('hoerdle_onboarding_completed');
+
+        if (hasCompletedOnboarding) {
+            return;
+        }
+
+        const driverObj = driver({
+            showProgress: true,
+            animate: true,
+            allowClose: true,
+            doneBtnText: 'Done',
+            nextBtnText: 'Next',
+            prevBtnText: 'Previous',
+            onDestroyed: () => {
+                localStorage.setItem('hoerdle_onboarding_completed', 'true');
+            },
+            steps: [
+                {
+                    element: '#tour-genres',
+                    popover: {
+                        title: 'Genres & Specials',
+                        description: 'Choose a specific genre or a curated special event here.',
+                        side: 'bottom',
+                        align: 'start'
+                    }
+                },
+                {
+                    element: '#tour-news',
+                    popover: {
+                        title: 'News',
+                        description: 'Stay updated with the latest news and announcements.',
+                        side: 'top',
+                        align: 'start'
+                    }
+                },
+                {
+                    element: '#tour-title',
+                    popover: {
+                        title: 'Hördle',
+                        description: 'This is the daily puzzle. One new song every day per genre.',
+                        side: 'bottom',
+                        align: 'start'
+                    }
+                },
+                {
+                    element: '#tour-status',
+                    popover: {
+                        title: 'Attempts',
+                        description: 'You have a limited number of attempts to guess the song.',
+                        side: 'bottom',
+                        align: 'start'
+                    }
+                },
+                {
+                    element: '#tour-score',
+                    popover: {
+                        title: 'Score',
+                        description: 'Your current score. Try to keep it high!',
+                        side: 'bottom',
+                        align: 'start'
+                    }
+                },
+                {
+                    element: '#tour-player',
+                    popover: {
+                        title: 'Player',
+                        description: 'Listen to the snippet. Each additional play reduces your potential score.',
+                        side: 'top',
+                        align: 'start'
+                    }
+                },
+                {
+                    element: '#tour-input',
+                    popover: {
+                        title: 'Input',
+                        description: 'Type your guess here. Search for artist or title.',
+                        side: 'top',
+                        align: 'start'
+                    }
+                },
+                {
+                    element: '#tour-controls',
+                    popover: {
+                        title: 'Controls',
+                        description: 'Start the music or skip to the next snippet if you\'re stuck.',
+                        side: 'top',
+                        align: 'start'
+                    }
+                }
+            ]
+        });
+
+        // Small delay to ensure DOM is ready
+        setTimeout(() => {
+            driverObj.drive();
+        }, 1000);
+
+    }, []);
+
+    return null;
+}
diff --git a/package-lock.json b/package-lock.json
index a9b8412..4414788 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10,6 +10,7 @@
       "dependencies": {
         "@prisma/client": "^6.19.0",
         "bcryptjs": "^3.0.3",
+        "driver.js": "^1.4.0",
         "music-metadata": "^11.10.2",
         "next": "16.0.3",
         "prisma": "^6.19.0",
@@ -2939,6 +2940,12 @@
         "url": "https://dotenvx.com"
       }
     },
+    "node_modules/driver.js": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/driver.js/-/driver.js-1.4.0.tgz",
+      "integrity": "sha512-Gm64jm6PmcU+si21sQhBrTAM1JvUrR0QhNmjkprNLxohOBzul9+pNHXgQaT9lW84gwg9GMLB3NZGuGolsz5uew==",
+      "license": "MIT"
+    },
     "node_modules/dunder-proto": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
diff --git a/package.json b/package.json
index 7038558..cff796a 100644
--- a/package.json
+++ b/package.json
@@ -11,6 +11,7 @@
   "dependencies": {
     "@prisma/client": "^6.19.0",
     "bcryptjs": "^3.0.3",
+    "driver.js": "^1.4.0",
     "music-metadata": "^11.10.2",
     "next": "16.0.3",
     "prisma": "^6.19.0",