feat: Complete TASK-006 - Starter Pokemon System with auto-claim

- Backend: /api/starter/claim endpoint creates 3 starters for new users
- Starters: Flametail Jr (Fire), Ripplefin (Water), Leaflet (Grass)
- Frontend: Auto-claim on first visit if collection is empty
- Manual claim button as fallback if auto-claim fails
- Added tests for auto-claim functionality
- Total: 156 tests passing

Auto-claim prevents the 'no Pokemon to start with' UX blocker.
New users automatically get 3 Common-type starters upon first load.

Author: nev-offload

PROGRESS.md

@@ -0,0 +1,23 @@
+# Pokemon App - Progress Log
+
+## 2026-02-12
+
+### 07:17 - TASK-006: Starter Pokemon System ✅ COMPLETED
+
+**What was done:**
+- Implemented auto-initialization of starter Pokemon for new users
+- Modified Collection.jsx to automatically claim starters when collection is empty
+- Added `hasAttemptedAutoClaim` ref to prevent infinite loops
+- Backend already had `/api/starter/claim` endpoint with 3 starters:
+  - Flametail Jr (Fire type, power 25)
+  - Ripplefin (Water type, power 25)
+  - Leaflet (Grass type, power 25)
+- Added tests for auto-claim behavior (2 tests)
+- All 156 tests now passing
+
+**Files modified:**
+- `src/pages/Collection.jsx` - Added auto-claim logic
+- `src/pages/Collection.test.jsx` - Added auto-claim tests
+- `TASKS.md` - Marked TASK-006 complete
+
+**Next priority:** TASK-008: Pokemon Creator Feature [P2 - Medium]

TASKS.md

@@ -39,10 +39,13 @@
 
 ### Active Tasks (CEO Priority Order)
 
-- [ ] **TASK-006: Starter Pokemon System** [P0 - Critical]
-  - New users start with 3 beginner Pokemon
-  - Ensure users can always catch (team can't be empty)
-  - Auto-initialize on first visit if no Pokemon owned
+- [x] **TASK-006: Starter Pokemon System** [P0 - Critical] ✅ COMPLETED
+  - ✅ Backend: `/api/starter/claim` endpoint in worker/index.js
+  - ✅ Three starter Pokemon defined (Flametail Jr, Ripplefin, Leaflet)
+  - ✅ API client: `claimStarters()` method
+  - ✅ Frontend: Auto-claim on first visit if collection is empty
+  - ✅ Manual claim button as fallback
+  - ✅ 2 tests added for auto-claim (156 total tests passing)
 
 - [x] **TASK-007: Base44 Data Migration** [P1 - High] ✅ COMPLETED
   - ✅ D1 database already seeded with 41 Pokemon

src/pages/Collection.jsx

@@ -20,11 +20,34 @@ export default function Collection({ onNavigate }) {
   const [teamMessage, setTeamMessage] = useState('');
   const pokemonCache = useRef(new Map());                // Cache: pokemon_id → pokemon data
 
+  // Track if we've attempted auto-claim to prevent loops
+  const hasAttemptedAutoClaim = useRef(false);
+
   // Initial load: just get the caught list (lightweight, no images)
+  // Auto-claim starters for new users
   useEffect(() => {
     (async () => {
       try {
         const caughtList = await pokemonAPI.getCaughtPokemon();
+        
+        // Auto-initialize starters for new users (empty collection, first visit)
+        if (caughtList.length === 0 && !hasAttemptedAutoClaim.current) {
+          hasAttemptedAutoClaim.current = true;
+          try {
+            const result = await pokemonAPI.claimStarters();
+            if (result.success) {
+              // Refresh the collection with new starters
+              const updatedList = await pokemonAPI.getCaughtPokemon();
+              setAllCaught(updatedList);
+              setIsLoading(false);
+              return;
+            }
+          } catch (claimErr) {
+            console.error('Auto-claim failed:', claimErr);
+            // Continue to normal flow even if auto-claim fails
+          }
+        }
+        
         setAllCaught(caughtList);
       } catch (err) {
         console.error("Failed to fetch collection:", err);

src/pages/Collection.test.jsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { render, screen, waitFor, fireEvent } from '@testing-library/react';
+import { render, screen, waitFor } from '@testing-library/react';
 import Collection from './Collection';
 import { pokemonAPI } from '@/api/client';
 
@@ -10,6 +10,7 @@ vi.mock('@/api/client', () => ({
     getPokemon: vi.fn(),
     updateCaughtPokemon: vi.fn(),
     releasePokemon: vi.fn(),
+    claimStarters: vi.fn(),
   },
 }));
 
@@ -31,21 +32,16 @@ describe('Collection Page', () => {
 
   it('should show loading state initially', () => {
     pokemonAPI.getCaughtPokemon.mockResolvedValue([]);
-    
     render(<Collection onNavigate={vi.fn()} />);
-    
-    expect(screen.getByText(/Loading Pokémon/i)).toBeInTheDocument();
+    expect(screen.getByText('⭐')).toBeInTheDocument();
   });
 
   it('should show empty state when no pokemon caught', async () => {
     pokemonAPI.getCaughtPokemon.mockResolvedValue([]);
-    
     render(<Collection onNavigate={vi.fn()} />);
-    
     await waitFor(() => {
-      expect(screen.queryByText(/Loading Pokémon/i)).not.toBeInTheDocument();
+      expect(screen.queryByText('⭐')).not.toBeInTheDocument();
     });
-    
     expect(screen.getByText(/Your collection is empty/i)).toBeInTheDocument();
     expect(screen.getByText(/Explore Wild Pokémon/i)).toBeInTheDocument();
   });
@@ -55,9 +51,9 @@ describe('Collection Page', () => {
       { id: 1, pokemon_id: 25, nickname: null, caught_date: '2024-01-01' },
       { id: 2, pokemon_id: 1, nickname: 'Bulby', caught_date: '2024-01-02' },
     ];
-    
+
     pokemonAPI.getCaughtPokemon.mockResolvedValue(caughtPokemon);
-    pokemonAPI.getPokemon.mockImplementation((id) => 
+    pokemonAPI.getPokemon.mockImplementation((id) =>
       Promise.resolve({
         id,
         name: id === 25 ? 'Pikachu' : 'Bulbasaur',
@@ -67,42 +63,84 @@ describe('Collection Page', () => {
         image_url: 'https://example.com/image.png',
       })
     );
-    
+
     render(<Collection onNavigate={vi.fn()} />);
-    
+
     await waitFor(() => {
-      expect(screen.queryByText(/Loading Pokémon/i)).not.toBeInTheDocument();
+      expect(screen.queryByText('⭐')).not.toBeInTheDocument();
     });
-    
+
     await waitFor(() => {
       expect(screen.getByText('Pikachu')).toBeInTheDocument();
     });
-    
+
     expect(screen.getByText('Bulby')).toBeInTheDocument();
   });
 
   it('should handle API errors gracefully', async () => {
     pokemonAPI.getCaughtPokemon.mockRejectedValue(new Error('Network error'));
-    
     render(<Collection onNavigate={vi.fn()} />);
-    
     await waitFor(() => {
-      expect(screen.queryByText(/Loading Pokémon/i)).not.toBeInTheDocument();
+      expect(screen.queryByText('⭐')).not.toBeInTheDocument();
     });
-    
     // Should show empty state or error message
     expect(screen.getByText(/Your collection is empty/i)).toBeInTheDocument();
   });
 
   it('should have navigation buttons', async () => {
     pokemonAPI.getCaughtPokemon.mockResolvedValue([]);
+    render(<Collection onNavigate={vi.fn()} />);
+    await waitFor(() => {
+      expect(screen.queryByText('⭐')).not.toBeInTheDocument();
+    });
+    expect(screen.getByText(/Explore Wild Pokémon/i)).toBeInTheDocument();
+  });
+
+  it('should auto-claim starter pokemon for new users', async () => {
+    const starterPokemon = [
+      { id: 1, pokemon_id: 'starter-1', nickname: null, caught_date: '2024-01-01' },
+      { id: 2, pokemon_id: 'starter-2', nickname: null, caught_date: '2024-01-01' },
+      { id: 3, pokemon_id: 'starter-3', nickname: null, caught_date: '2024-01-01' },
+    ];
 
+    // Empty at first, then has starters after claiming
+    pokemonAPI.getCaughtPokemon
+      .mockResolvedValueOnce([])
+      .mockResolvedValueOnce(starterPokemon);
+    
+    pokemonAPI.claimStarters.mockResolvedValue({
+      success: true,
+      message: 'Welcome to the world of Pokemon! You received 3 starter Pokemon!',
+      starters: [
+        { caught_id: 1, name: 'Flametail Jr' },
+        { caught_id: 2, name: 'Ripplefin' },
+        { caught_id: 3, name: 'Leaflet' },
+      ],
+    });
+
     render(<Collection onNavigate={vi.fn()} />);
 
     await waitFor(() => {
-      expect(screen.queryByText(/Loading Pokémon/i)).not.toBeInTheDocument();
+      expect(pokemonAPI.claimStarters).toHaveBeenCalledTimes(1);
     });
 
-    expect(screen.getByText(/Explore Wild Pokémon/i)).toBeInTheDocument();
+    // Should fetch the collection twice (empty, then with starters)
+    expect(pokemonAPI.getCaughtPokemon).toHaveBeenCalledTimes(2);
+  });
+
+  it('should handle auto-claim failure gracefully', async () => {
+    // Empty collection
+    pokemonAPI.getCaughtPokemon.mockResolvedValue([]);
+    pokemonAPI.claimStarters.mockRejectedValue(new Error('API Error'));
+
+    render(<Collection onNavigate={vi.fn()} />);
+    
+    await waitFor(() => {
+      expect(screen.queryByText('⭐')).not.toBeInTheDocument();
+    });
+    
+    // Should show empty state even if auto-claim failed
+    expect(screen.getByText(/Your collection is empty/i)).toBeInTheDocument();
+    expect(screen.getByText(/Claim Your Starter Pokémon/i)).toBeInTheDocument();
   });
 });