add leaderboard persistent storage and fix styling

.env.example

@@ -0,0 +1,13 @@
+# OpenRouter API Key (for AI functionality)
+OPENROUTER_API_KEY=your_openrouter_key_here
+
+# Hugging Face API Token (for leaderboard persistence)
+# Get your token from: https://huggingface.co/settings/tokens
+# Required permissions: write access to datasets
+HF_TOKEN=your_hf_token_here
+# OR use HF_API_KEY (both work)
+HF_API_KEY=your_hf_token_here
+
+# Hugging Face Leaderboard Repository (optional, defaults to zmuhls/cloze-reader-leaderboard)
+# Format: username/repo-name
+HF_LEADERBOARD_REPO=your_username/cloze-reader-leaderboard

HF_LEADERBOARD_SETUP.md

@@ -0,0 +1,222 @@
+# Hugging Face Leaderboard Setup
+
+This document explains how the HF Hub leaderboard integration works and how to set it up.
+
+## Overview
+
+The leaderboard system now supports two modes:
+1. **HF Hub Mode** (persistent, shared across all users)
+2. **localStorage Mode** (fallback, local to browser)
+
+When HF Hub is available, all leaderboard entries are:
+- Saved to a HF Hub dataset repository
+- Automatically synced across all users
+- Version controlled with commit history
+- Persistent across sessions and devices
+
+## Setup Instructions
+
+### 1. Get Hugging Face Token
+
+1. Go to https://huggingface.co/settings/tokens
+2. Create a new token with **write** access
+3. Copy the token value
+
+### 2. Configure Environment Variables
+
+Create a `.env` file in the project root (copy from `.env.example`):
+
+```bash
+# Hugging Face API Token
+HF_TOKEN=hf_your_token_here
+
+# Optional: Custom repository name (defaults to zmuhls/cloze-reader-leaderboard)
+HF_LEADERBOARD_REPO=your_username/your-repo-name
+```
+
+### 3. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+This will install `huggingface-hub` along with other dependencies.
+
+### 4. Run the Server
+
+```bash
+# Production mode (with HF backend)
+make dev-python
+# OR
+python app.py
+
+# The server will:
+# 1. Check for HF_TOKEN in environment
+# 2. Create the HF dataset repository if it doesn't exist
+# 3. Initialize with empty leaderboard
+# 4. Handle all read/write operations via API endpoints
+```
+
+### 5. Test the Integration
+
+Visit `http://localhost:7860` and:
+1. Play the game to reach Level 2
+2. Enter your initials
+3. Check browser console for HF sync messages:
+   - `🔧 LEADERBOARD: Using HF Hub backend`
+   - `📤 LEADERBOARD: Saved to HF Hub`
+   - `📥 LEADERBOARD: Synced from HF Hub`
+
+## Architecture
+
+### Backend (Python)
+
+**`hf_leaderboard.py`** - HF Hub integration service
+- Creates/manages HF dataset repository
+- Handles leaderboard read/write/update operations
+- Auto-commits changes to HF Hub
+- Uses `huggingface_hub` Python library
+
+**`app.py`** - FastAPI endpoints
+- `GET /api/leaderboard` - Fetch current leaderboard
+- `POST /api/leaderboard/add` - Add new entry
+- `POST /api/leaderboard/update` - Replace entire leaderboard
+- `DELETE /api/leaderboard/clear` - Clear all entries (admin)
+
+### Frontend (JavaScript)
+
+**`src/hfLeaderboardAPI.js`** - API client
+- Communicates with FastAPI backend
+- Handles network errors gracefully
+- Provides async methods for all operations
+
+**`src/leaderboardService.js`** - Service layer (updated)
+- Checks HF availability on init
+- Syncs from HF Hub on page load
+- Saves to both HF and localStorage
+- Falls back to localStorage if HF unavailable
+
+## Data Format
+
+Leaderboard entries are stored as JSON on HF Hub:
+
+```json
+{
+  "leaderboard": [
+    {
+      "initials": "ABC",
+      "level": 5,
+      "round": 2,
+      "passagesPassed": 18,
+      "date": "2025-01-31T12:00:00.000Z"
+    }
+  ],
+  "last_updated": "2025-01-31T12:00:00.000Z",
+  "version": "1.0"
+}
+```
+
+## How It Works
+
+### On Page Load
+1. Frontend checks if backend is available (`/api/leaderboard`)
+2. If available, sets `useHF = true`
+3. Syncs leaderboard from HF Hub to localStorage
+4. User sees most recent global leaderboard
+
+### When Player Achieves High Score
+1. Entry saved to localStorage immediately (fast UI update)
+2. Entry sent to backend API (`POST /api/leaderboard/add`)
+3. Backend adds entry to HF Hub with auto-commit
+4. All other users will see updated leaderboard on next load
+
+### Fallback Behavior
+If HF backend is unavailable (no token, network error, etc.):
+- System automatically uses localStorage only
+- Leaderboard still works, just not shared
+- Console shows: `⚠️ LEADERBOARD: HF backend unavailable, using localStorage`
+
+## Viewing Your HF Dataset
+
+After first save, visit:
+```
+https://huggingface.co/datasets/YOUR_USERNAME/cloze-reader-leaderboard
+```
+
+You'll see:
+- `leaderboard.json` file
+- Commit history of all updates
+- Public leaderboard accessible to all
+
+## Production Deployment
+
+### Hugging Face Spaces
+If deploying on HF Spaces, the token is automatically available:
+```python
+# HF Spaces provides HF_TOKEN automatically
+# No .env file needed!
+```
+
+### Other Platforms (Vercel, Railway, etc.)
+Add `HF_TOKEN` to your platform's environment variables:
+- Vercel: Project Settings → Environment Variables
+- Railway: Project → Variables
+- Render: Environment → Environment Variables
+
+## Security Notes
+
+- ✅ HF Token stored securely in backend environment
+- ✅ Token never exposed to frontend/browser
+- ✅ All HF operations go through backend API
+- ✅ CORS configured for security
+- ⚠️ Leaderboard dataset should be **public** (read access for all users)
+- ⚠️ Write access controlled via backend (users can't directly modify HF dataset)
+
+## Troubleshooting
+
+### "No HF token available for writing"
+- Check `.env` file has `HF_TOKEN` or `HF_API_KEY`
+- Restart server after adding token
+- Verify token has write permissions
+
+### "Failed to create HF repo"
+- Check token permissions (need write access)
+- Verify repository name format (username/repo-name)
+- Check if repo already exists
+
+### Leaderboard not syncing
+- Check browser console for error messages
+- Verify backend is running (`http://localhost:7860/api/leaderboard`)
+- Check network tab for failed API calls
+- Ensure HF Hub is accessible (not blocked by firewall)
+
+### Backend logs show errors
+```bash
+# Check logs for detailed error messages
+python app.py
+
+# Look for:
+# ✅ "Using existing HF dataset: ..."
+# ✅ "Leaderboard saved to HF Hub: ..."
+# ❌ "Failed to upload to HF Hub: ..."
+```
+
+## Development vs Production
+
+**Local Development** (`make dev` - static server):
+- Uses localStorage only
+- No backend, no HF sync
+- Fast iteration, no setup needed
+
+**Production** (`make dev-python` - FastAPI server):
+- Uses HF Hub backend
+- Requires token and backend running
+- Shared global leaderboard
+
+## API Documentation
+
+Once server is running, visit:
+- FastAPI docs: `http://localhost:7860/docs`
+- Alternative docs: `http://localhost:7860/redoc`
+
+Interactive API testing available through Swagger UI!

app.py

@@ -1,14 +1,54 @@
-from fastapi import FastAPI
+from fastapi import FastAPI, HTTPException
 from fastapi.responses import HTMLResponse, RedirectResponse
 from fastapi.staticfiles import StaticFiles
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from typing import List, Optional
 import os
 from dotenv import load_dotenv
+import logging
 
 # Load environment variables from .env file
 load_dotenv()
 
+# Import HF Leaderboard Service
+from hf_leaderboard import HFLeaderboardService
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
 app = FastAPI()
 
+# Add CORS middleware for local development
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Initialize HF Leaderboard Service
+hf_token = os.getenv("HF_TOKEN") or os.getenv("HF_API_KEY")
+hf_leaderboard = HFLeaderboardService(
+    repo_id=os.getenv("HF_LEADERBOARD_REPO", "zmuhls/cloze-reader-leaderboard"),
+    token=hf_token
+)
+
+# Pydantic models for API
+class LeaderboardEntry(BaseModel):
+    initials: str
+    level: int
+    round: int
+    passagesPassed: int
+    date: str
+
+class LeaderboardResponse(BaseModel):
+    success: bool
+    leaderboard: List[LeaderboardEntry]
+    message: Optional[str] = None
+
 # Mount static files
 app.mount("/src", StaticFiles(directory="src"), name="src")
 
@@ -39,6 +79,89 @@ async def read_root():
     
     return HTMLResponse(content=html_content)
 
+
+# ===== LEADERBOARD API ENDPOINTS =====
+
+@app.get("/api/leaderboard", response_model=LeaderboardResponse)
+async def get_leaderboard():
+    """
+    Get current leaderboard data from HF Hub
+    """
+    try:
+        leaderboard = hf_leaderboard.get_leaderboard()
+        return {
+            "success": True,
+            "leaderboard": leaderboard,
+            "message": f"Retrieved {len(leaderboard)} entries"
+        }
+    except Exception as e:
+        logger.error(f"Error fetching leaderboard: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/leaderboard/add")
+async def add_leaderboard_entry(entry: LeaderboardEntry):
+    """
+    Add new entry to leaderboard
+    """
+    try:
+        success = hf_leaderboard.add_entry(entry.dict())
+        if success:
+            return {
+                "success": True,
+                "message": f"Added {entry.initials} to leaderboard"
+            }
+        else:
+            raise HTTPException(status_code=500, detail="Failed to add entry")
+    except ValueError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error adding entry: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/leaderboard/update")
+async def update_leaderboard(entries: List[LeaderboardEntry]):
+    """
+    Update entire leaderboard (replace all data)
+    """
+    try:
+        success = hf_leaderboard.update_leaderboard([e.dict() for e in entries])
+        if success:
+            return {
+                "success": True,
+                "message": "Leaderboard updated successfully"
+            }
+        else:
+            raise HTTPException(status_code=500, detail="Failed to update leaderboard")
+    except ValueError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error updating leaderboard: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.delete("/api/leaderboard/clear")
+async def clear_leaderboard():
+    """
+    Clear all leaderboard data (admin only)
+    """
+    try:
+        success = hf_leaderboard.clear_leaderboard()
+        if success:
+            return {
+                "success": True,
+                "message": "Leaderboard cleared"
+            }
+        else:
+            raise HTTPException(status_code=500, detail="Failed to clear leaderboard")
+    except ValueError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error clearing leaderboard: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
 if __name__ == "__main__":
     import uvicorn
     uvicorn.run(app, host="0.0.0.0", port=7860)

hf_leaderboard.py

@@ -0,0 +1,227 @@
+"""
+Hugging Face Leaderboard Service
+Manages leaderboard data persistence using HF Hub
+"""
+
+import json
+import os
+from datetime import datetime
+from typing import List, Dict, Optional
+from huggingface_hub import HfApi, hf_hub_download, HfFolder
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class HFLeaderboardService:
+    """
+    Service for managing leaderboard data on Hugging Face Hub
+    Stores leaderboard as a JSON file in a HF dataset
+    """
+
+    def __init__(self, repo_id: str = "zmuhls/cloze-reader-leaderboard", token: Optional[str] = None):
+        """
+        Initialize HF Leaderboard Service
+
+        Args:
+            repo_id: HF Hub repository ID (format: username/repo-name)
+            token: HF API token (if not provided, uses HF_TOKEN env var)
+        """
+        self.repo_id = repo_id
+        self.token = token or os.getenv("HF_TOKEN") or os.getenv("HF_API_KEY")
+        self.api = HfApi()
+        self.leaderboard_file = "leaderboard.json"
+
+        if not self.token:
+            logger.warning("No HF token provided. Read-only mode (if repo is public)")
+
+        # Ensure repo exists
+        self._ensure_repo_exists()
+
+    def _ensure_repo_exists(self):
+        """Create the HF dataset repository if it doesn't exist"""
+        if not self.token:
+            return
+
+        try:
+            # Try to get repo info
+            self.api.repo_info(repo_id=self.repo_id, repo_type="dataset", token=self.token)
+            logger.info(f"Using existing HF dataset: {self.repo_id}")
+        except Exception as e:
+            # Repo doesn't exist, create it
+            try:
+                self.api.create_repo(
+                    repo_id=self.repo_id,
+                    repo_type="dataset",
+                    token=self.token,
+                    private=False,
+                    exist_ok=True
+                )
+                logger.info(f"Created HF dataset: {self.repo_id}")
+
+                # Initialize with empty leaderboard
+                self._save_to_hub([])
+            except Exception as create_error:
+                logger.error(f"Failed to create HF repo: {create_error}")
+
+    def _save_to_hub(self, data: List[Dict]):
+        """
+        Save leaderboard data to HF Hub
+
+        Args:
+            data: List of leaderboard entries
+        """
+        if not self.token:
+            raise ValueError("No HF token available for writing")
+
+        # Create temporary file
+        temp_file = f"/tmp/{self.leaderboard_file}"
+        with open(temp_file, "w") as f:
+            json.dump({
+                "leaderboard": data,
+                "last_updated": datetime.utcnow().isoformat(),
+                "version": "1.0"
+            }, f, indent=2)
+
+        # Upload to HF Hub
+        try:
+            self.api.upload_file(
+                path_or_fileobj=temp_file,
+                path_in_repo=self.leaderboard_file,
+                repo_id=self.repo_id,
+                repo_type="dataset",
+                token=self.token,
+                commit_message=f"Update leaderboard - {datetime.utcnow().strftime('%Y-%m-%d %H:%M:%S')} UTC"
+            )
+            logger.info(f"Leaderboard saved to HF Hub: {self.repo_id}")
+        except Exception as e:
+            logger.error(f"Failed to upload to HF Hub: {e}")
+            raise
+        finally:
+            # Clean up temp file
+            if os.path.exists(temp_file):
+                os.remove(temp_file)
+
+    def _load_from_hub(self) -> List[Dict]:
+        """
+        Load leaderboard data from HF Hub
+
+        Returns:
+            List of leaderboard entries
+        """
+        try:
+            # Download file from HF Hub
+            file_path = hf_hub_download(
+                repo_id=self.repo_id,
+                filename=self.leaderboard_file,
+                repo_type="dataset",
+                token=self.token
+            )
+
+            with open(file_path, "r") as f:
+                data = json.load(f)
+                return data.get("leaderboard", [])
+        except Exception as e:
+            logger.warning(f"Failed to load from HF Hub: {e}. Returning empty leaderboard.")
+            return []
+
+    def get_leaderboard(self) -> List[Dict]:
+        """
+        Get current leaderboard data
+
+        Returns:
+            List of leaderboard entries sorted by rank
+        """
+        return self._load_from_hub()
+
+    def add_entry(self, entry: Dict) -> bool:
+        """
+        Add new entry to leaderboard
+
+        Args:
+            entry: Leaderboard entry with keys: initials, level, round, passagesPassed, date
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if not self.token:
+            raise ValueError("No HF token available for writing")
+
+        try:
+            # Load current leaderboard
+            leaderboard = self._load_from_hub()
+
+            # Add new entry
+            leaderboard.append(entry)
+
+            # Sort leaderboard (highest level first, then round, then passages)
+            leaderboard = self._sort_leaderboard(leaderboard)
+
+            # Keep only top 10
+            leaderboard = leaderboard[:10]
+
+            # Save back to hub
+            self._save_to_hub(leaderboard)
+
+            logger.info(f"Added entry to leaderboard: {entry['initials']} - Level {entry['level']}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to add entry: {e}")
+            return False
+
+    def update_leaderboard(self, leaderboard: List[Dict]) -> bool:
+        """
+        Replace entire leaderboard with new data
+
+        Args:
+            leaderboard: Complete leaderboard data
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if not self.token:
+            raise ValueError("No HF token available for writing")
+
+        try:
+            # Sort and limit to top 10
+            sorted_board = self._sort_leaderboard(leaderboard)[:10]
+            self._save_to_hub(sorted_board)
+            return True
+        except Exception as e:
+            logger.error(f"Failed to update leaderboard: {e}")
+            return False
+
+    def _sort_leaderboard(self, entries: List[Dict]) -> List[Dict]:
+        """
+        Sort leaderboard entries by performance
+
+        Args:
+            entries: List of leaderboard entries
+
+        Returns:
+            Sorted list (best first)
+        """
+        return sorted(entries, key=lambda x: (
+            -x.get('level', 0),  # Higher level is better
+            -x.get('round', 0),  # Higher round is better
+            -x.get('passagesPassed', 0),  # More passages is better
+            x.get('date', '')  # Newer is better (date sorts ascending)
+        ))
+
+    def clear_leaderboard(self) -> bool:
+        """
+        Clear all leaderboard data (admin function)
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if not self.token:
+            raise ValueError("No HF token available for writing")
+
+        try:
+            self._save_to_hub([])
+            logger.info("Leaderboard cleared")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to clear leaderboard: {e}")
+            return False

index.html

@@ -58,6 +58,7 @@
             <button type="button" id="hint-btn" class="typewriter-button">
                 Show Hints
             </button>
+            <div class="controls-divider"></div>
             <button id="leaderboard-btn" class="leaderboard-footer-btn" title="View leaderboard">
                 🏅
             </button>

requirements.txt

@@ -1,3 +1,4 @@
 fastapi==0.104.1
 uvicorn[standard]==0.24.0
-python-dotenv==1.0.0
+python-dotenv==1.0.0
+huggingface-hub==0.20.3

src/hfLeaderboardAPI.js

@@ -0,0 +1,164 @@
+/**
+ * HF Leaderboard API Client
+ * Communicates with FastAPI backend for HF Hub leaderboard persistence
+ */
+
+export class HFLeaderboardAPI {
+  constructor(baseUrl = '') {
+    // If no baseUrl provided, use current origin (works for both dev and production)
+    this.baseUrl = baseUrl || window.location.origin;
+  }
+
+  /**
+   * Get leaderboard from HF Hub
+   * @returns {Promise<Array>} Array of leaderboard entries
+   */
+  async getLeaderboard() {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/leaderboard`, {
+        method: 'GET',
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      const data = await response.json();
+
+      if (data.success) {
+        console.log('📥 HF API: Retrieved leaderboard', {
+          entries: data.leaderboard.length,
+          message: data.message
+        });
+        return data.leaderboard;
+      } else {
+        throw new Error(data.message || 'Failed to retrieve leaderboard');
+      }
+    } catch (error) {
+      console.error('❌ HF API: Error fetching leaderboard:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Add new entry to leaderboard
+   * @param {Object} entry - Leaderboard entry {initials, level, round, passagesPassed, date}
+   * @returns {Promise<Object>} Response object
+   */
+  async addEntry(entry) {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/leaderboard/add`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(entry)
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({ detail: response.statusText }));
+        throw new Error(`HTTP ${response.status}: ${errorData.detail || response.statusText}`);
+      }
+
+      const data = await response.json();
+
+      console.log('✅ HF API: Added entry', {
+        initials: entry.initials,
+        level: entry.level,
+        message: data.message
+      });
+
+      return data;
+    } catch (error) {
+      console.error('❌ HF API: Error adding entry:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Update entire leaderboard
+   * @param {Array} entries - Array of leaderboard entries
+   * @returns {Promise<Object>} Response object
+   */
+  async updateLeaderboard(entries) {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/leaderboard/update`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(entries)
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({ detail: response.statusText }));
+        throw new Error(`HTTP ${response.status}: ${errorData.detail || response.statusText}`);
+      }
+
+      const data = await response.json();
+
+      console.log('✅ HF API: Updated leaderboard', {
+        entries: entries.length,
+        message: data.message
+      });
+
+      return data;
+    } catch (error) {
+      console.error('❌ HF API: Error updating leaderboard:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Clear all leaderboard data (admin function)
+   * @returns {Promise<Object>} Response object
+   */
+  async clearLeaderboard() {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/leaderboard/clear`, {
+        method: 'DELETE',
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({ detail: response.statusText }));
+        throw new Error(`HTTP ${response.status}: ${errorData.detail || response.statusText}`);
+      }
+
+      const data = await response.json();
+
+      console.log('✅ HF API: Cleared leaderboard', {
+        message: data.message
+      });
+
+      return data;
+    } catch (error) {
+      console.error('❌ HF API: Error clearing leaderboard:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Check if HF backend is available
+   * @returns {Promise<boolean>} True if backend is reachable
+   */
+  async isAvailable() {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/leaderboard`, {
+        method: 'GET',
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      });
+      return response.ok;
+    } catch (error) {
+      console.warn('⚠️ HF API: Backend not available, will use localStorage fallback');
+      return false;
+    }
+  }
+}

src/leaderboardService.js

@@ -1,9 +1,11 @@
 /**
  * Leaderboard Service
- * Manages high scores, player stats, and localStorage persistence
+ * Manages high scores, player stats, with HF Hub persistence and localStorage fallback
  * Following arcade conventions with 3-letter initials and top 10 tracking
  */
 
+import { HFLeaderboardAPI } from './hfLeaderboardAPI.js';
+
 export class LeaderboardService {
   constructor() {
     this.storageKeys = {
@@ -14,9 +16,49 @@ export class LeaderboardService {
 
     this.maxEntries = 10;
 
+    // Initialize HF API client
+    this.hfAPI = new HFLeaderboardAPI();
+    this.useHF = false; // Will be set based on availability check
+
+    // Check HF availability and initialize
+    this.initializeAsync();
+  }
+
+  /**
+   * Async initialization to check HF availability
+   */
+  async initializeAsync() {
+    try {
+      this.useHF = await this.hfAPI.isAvailable();
+      console.log(`🔧 LEADERBOARD: Using ${this.useHF ? 'HF Hub backend' : 'localStorage only'}`);
+    } catch (error) {
+      console.warn('⚠️ LEADERBOARD: HF backend unavailable, using localStorage', error);
+      this.useHF = false;
+    }
+
     // Reset all data on initialization (fresh start each session)
     this.resetAll();
     this.initializeStorage();
+
+    // If HF is available, sync from HF to localStorage
+    if (this.useHF) {
+      await this.syncFromHF();
+    }
+  }
+
+  /**
+   * Sync leaderboard from HF Hub to localStorage
+   */
+  async syncFromHF() {
+    try {
+      const hfLeaderboard = await this.hfAPI.getLeaderboard();
+      if (hfLeaderboard && hfLeaderboard.length > 0) {
+        this.saveLeaderboard(hfLeaderboard);
+        console.log('📥 LEADERBOARD: Synced from HF Hub', { entries: hfLeaderboard.length });
+      }
+    } catch (error) {
+      console.error('❌ LEADERBOARD: Failed to sync from HF', error);
+    }
   }
 
   /**
@@ -223,7 +265,7 @@ export class LeaderboardService {
   /**
    * Add a new entry to the leaderboard
    */
-  addEntry(initials, level, round, passagesPassed) {
+  async addEntry(initials, level, round, passagesPassed) {
     const validInitials = this.validateInitials(initials);
     if (!validInitials) {
       console.error('Invalid initials:', initials);
@@ -246,7 +288,19 @@ export class LeaderboardService {
     const trimmed = sorted.slice(0, this.maxEntries);
     this.saveLeaderboard(trimmed);
 
-    return sorted.findIndex(entry => entry === newEntry) + 1; // Return rank
+    const rank = sorted.findIndex(entry => entry === newEntry) + 1;
+
+    // If HF is available, also save to HF Hub
+    if (this.useHF) {
+      try {
+        await this.hfAPI.addEntry(newEntry);
+        console.log('📤 LEADERBOARD: Saved to HF Hub', { initials: validInitials, level, rank });
+      } catch (error) {
+        console.error('❌ LEADERBOARD: Failed to save to HF, localStorage only', error);
+      }
+    }
+
+    return rank; // Return rank
   }
 
   /**

src/styles.css

@@ -428,28 +428,39 @@
 
   /* Leaderboard button in footer */
   .leaderboard-footer-btn {
-    background: none;
-    border: none;
+    background-color: var(--aged-paper-dark);
+    color: var(--typewriter-ink);
+    border: 2px solid black;
+    border-radius: 0 8px 8px 0;
     padding: 8px 16px;
     cursor: pointer;
     font-size: 1.5rem;
     line-height: 1;
-    transition: transform 0.2s ease, filter 0.2s ease;
+    transition: all 0.15s ease;
     display: flex;
     align-items: center;
     justify-content: center;
-    position: absolute;
-    right: 16px;
-    top: 50%;
-    transform: translateY(-50%);
+    flex: 0 0 auto;
+    min-width: 60px;
+    min-height: 44px;
+    box-shadow:
+      0 3px 0 rgba(0, 0, 0, 0.3),
+      0 4px 8px rgba(0, 0, 0, 0.1);
   }
 
   .leaderboard-footer-btn:hover {
-    transform: translateY(-50%) scale(1.2);
+    background-color: rgba(0, 0, 0, 0.05);
+    transform: translateY(-1px);
+    box-shadow:
+      0 4px 0 rgba(0, 0, 0, 0.3),
+      0 6px 12px rgba(0, 0, 0, 0.15);
   }
 
   .leaderboard-footer-btn:active {
-    transform: translateY(-50%) scale(1.05);
+    transform: translateY(2px);
+    box-shadow:
+      0 1px 0 rgba(0, 0, 0, 0.3),
+      0 2px 4px rgba(0, 0, 0, 0.1);
   }
 
 
@@ -477,8 +488,9 @@
 
     .leaderboard-footer-btn {
       font-size: 1.25rem;
-      padding: 6px 12px;
-      right: 12px;
+      padding: 12px 10px;
+      min-width: 50px;
+      min-height: 48px;
     }
   }
 
@@ -502,8 +514,8 @@
 
     .leaderboard-footer-btn {
       font-size: 1.1rem;
-      padding: 4px 10px;
-      right: 8px;
+      padding: 12px 8px;
+      min-width: 48px;
     }
   }
 
@@ -735,34 +747,39 @@
     gap: 12px;
     padding: 14px 16px;
     background: var(--aged-paper-dark);
-    border: 2px solid rgba(0, 0, 0, 0.2);
+    border: 3px solid rgba(0, 0, 0, 0.4);
     border-radius: 6px;
     font-family: 'Courier New', monospace;
     transition: all 0.2s ease;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.15);
   }
 
   /* Rank Colors */
   .leaderboard-entry.rank-gold {
-    background: linear-gradient(135deg, #fff7e6 0%, #ffeaa7 100%);
-    border-color: #d4af37;
-    border-width: 3px;
-    box-shadow: 0 2px 8px rgba(212, 175, 55, 0.3);
+    background: linear-gradient(135deg, #fff7e6 0%, #ffd700 100%);
+    border-color: #b8860b;
+    border-width: 4px;
+    box-shadow: 0 4px 12px rgba(184, 134, 11, 0.4), inset 0 1px 0 rgba(255, 255, 255, 0.5);
   }
 
   .leaderboard-entry.rank-silver {
-    background: linear-gradient(135deg, #fff9f2 0%, #f5deb3 100%);
-    border-color: #c9a869;
-    border-width: 2px;
+    background: linear-gradient(135deg, #fff9f2 0%, #e6d7b8 100%);
+    border-color: #a0826d;
+    border-width: 3px;
+    box-shadow: 0 3px 8px rgba(160, 130, 109, 0.3);
   }
 
   .leaderboard-entry.rank-standard {
-    background: var(--aged-paper-dark);
+    background: #ffffff;
+    border-color: rgba(0, 0, 0, 0.3);
+    border-width: 2px;
   }
 
   .leaderboard-entry.player-entry {
-    background: linear-gradient(135deg, #fff9f0 0%, #ffecd1 100%);
-    border-color: #d4a574;
-    border-width: 3px;
+    background: linear-gradient(135deg, #fff9f0 0%, #ffd89b 100%);
+    border-color: #cc8800;
+    border-width: 4px;
+    box-shadow: 0 4px 12px rgba(204, 136, 0, 0.35);
   }
 
   .leaderboard-entry:hover {