# Tutorial Redesign Plan

Based on the Figma mockups in `feedback/` folder and colleague's feedback.

## Overview of New Flow

```
┌─────────────────┐
│  Welcome Modal  │  "FIRE NATION ATTACK" + Your Mission + Reachy diagram
│  [SKIP] [BEGIN] │
└────────┬────────┘
         │ BEGIN TUTORIAL
         ▼
┌─────────────────┐
│ Step 1: Enemies │  "Fire enemies appear from the left..."
│  [SKIP] [NEXT]  │
└────────┬────────┘
         ▼
┌─────────────────┐
│ Step 2: Water   │  "Your water supply is limited..."
│  [SKIP] [NEXT]  │
└────────┬────────┘
         ▼
┌─────────────────┐
│ Step 3: Move    │  INTERACTIVE - "Move head onto path"
│  (auto-advance) │  → waits for cursor on enemy path
└────────┬────────┘
         ▼
┌─────────────────┐
│ Step 4: Spray   │  INTERACTIVE - "Activate left antenna to spray"
│  (auto-advance) │  → waits for spray action
└────────┬────────┘
         ▼
┌─────────────────┐
│ Step 5: Vacuum  │  INTERACTIVE - "Activate right antenna to vacuum"
│  (auto-advance) │  → waits for vacuum action
└────────┬────────┘
         ▼
┌─────────────────┐
│ Difficulty      │  "SPRAY A DIFFICULTY TO BEGIN"
│ EASY MED HARD   │  (no leaderboard here)
└────────┬────────┘
         │ Game plays...
         ▼
┌─────────────────┐
│ Game Over /     │  Score + Leaderboard shown HERE
│ Victory         │  (moved from start screen)
└─────────────────┘
```

## Implementation Tasks

### 1. New Game Phases
Add new phases to the state machine:
- `"welcome"` - Initial modal with mission explanation
- `"tutorial_enemies"` - Step explaining enemies
- `"tutorial_water"` - Step explaining water tank
- `"tutorial_move"` - Interactive: move cursor to path
- `"tutorial_spray"` - Interactive: spray water
- `"tutorial_vacuum"` - Interactive: vacuum water
- `"difficulty_select"` - Current "waiting" phase, but without leaderboard

### 2. Welcome Modal (Frame 1)
- Full-screen dark modal with cyan border
- "FIRE NATION ATTACK" title (large, orange gradient text)
- "Your Mission" section with explanation text
- Reachy Mini diagram showing controls:
  - Right Antenna → Vacuum Puddles
  - Left Antenna → Spray Water
  - Head & Body → Move Cursor
- Two buttons: "X SKIP TUTORIAL" and "BEGIN TUTORIAL"

**Decision needed:** Should the Reachy diagram be:
- A) An SVG/PNG asset (cleaner, matches Figma exactly)
- B) Drawn with Canvas (more work, but no external assets)
- C) CSS/HTML illustration (middle ground)

### 3. Tutorial Step Modals (Frames 2-3)
Centered modal cards with:
- Icon at top (fire icon, water droplet icon)
- Title in cyan ("FIRE ENEMIES", "WATER TANK")
- Description text in gray
- "X SKIP" link (cyan, underlined) on left
- "NEXT>" button (cyan filled) on right

### 4. Interactive Tutorial Steps (Frames 4-6)
Left-side panel (not centered) showing:
- Reachy Mini diagram with highlighted part
- Instruction title in orange ("MOVE HEAD AND BODY", "ACTIVATE LEFT ANTENNA", etc.)
- Description text
- Game scene visible in background with demo enemy + path

**For Step 3 (Move):**
- Spawn a single demo enemy with visible path
- Detect when cursor overlaps with the enemy's path
- Auto-advance when detected

**For Step 4 (Spray):**
- Keep demo enemy on screen
- Detect when user pulls left antenna (spray action)
- Auto-advance when detected

**For Step 5 (Vacuum):**
- Maybe spawn a puddle or highlight the well?
- Detect when user pulls right antenna (vacuum action)
- Auto-advance when detected

### 5. Difficulty Select Screen (Frame 7)
- "SPRAY A DIFFICULTY TO BEGIN" text with cursor icon
- Large circular buttons: EASY (yellow), MEDIUM (orange), HARD (red)
- NO leaderboard on this screen
- Remove the current tutorial arrows (replaced by new tutorial flow)

### 6. Move Leaderboard to End
- Remove leaderboard panel from start/waiting screen
- Show leaderboard in gameover/victory screens
- Keep the "login to publish" message for non-logged users

### 7. Detect HuggingFace Login Status
**Question:** Is there an API endpoint to check if user is logged in?
- If yes: Conditionally show "login to publish scores" message
- If no: Always show the message (current behavior)

Possible approach: Try to fetch user info from HF Space API or check for auth cookies/headers.

## Design Tokens (from Figma)

```
Colors:
- Background: #0a1628 (dark navy)
- Modal background: #0d1f35 (slightly lighter navy)
- Modal border: #1a3a5c (cyan-tinted border)
- Primary cyan: #00d4ff
- Title orange: linear-gradient(#ff6b35, #ff9500)
- Text gray: #8899aa
- EASY: #ffcc00
- MEDIUM: #ff8800
- HARD: #ff3366

Typography:
- Title: Bold, all-caps, large (~48px)
- Headings: Bold, all-caps, medium (~24px)
- Body: Regular, sentence case (~16px)
```

## Open Questions for Discussion

1. **Reachy diagram asset**: PNG/SVG from designer, or recreate in code?

2. **Interactive tutorial timing**:
   - Should there be a minimum time before auto-advancing?
   - What if user is stuck? Add a "skip this step" option?

3. **Tutorial persistence**:
   - Should we remember if user completed tutorial (localStorage)?
   - Skip tutorial on subsequent visits?

4. **Demo enemy behavior**:
   - Should demo enemy actually die when sprayed during tutorial?
   - Or just detect the action and move on?

5. **Countdown after difficulty select**:
   - Colleague mentioned "3...2...1... C'est parti" countdown
   - Add animated countdown before Wave 1 starts?

6. **Vacuum tutorial step**:
   - Frame 6 shows "vacuum water" but there's no puddle visible
   - Should we spawn a puddle for this step? Or point to the Sacred Well?

## Estimated Scope

This is a significant refactor touching:
- Game state machine (new phases)
- UI rendering (new modals, panels)
- Input handling (detecting tutorial completion)
- HTML/CSS (modal styling, possibly new elements)
- Potentially new image assets

Suggest implementing in stages:
1. Phase 1: Welcome modal + skip flow
2. Phase 2: Text-based tutorial steps (non-interactive)
3. Phase 3: Interactive tutorial steps
4. Phase 4: Move leaderboard to end
5. Phase 5: Polish & HF login detection (if possible)