rehearshalhub/black_screen_debug.md

# Black Screen Debugging Guide

## Issue Description
Users are experiencing black screens when navigating in the mobile menu, particularly when clicking the Library button.

## Debugging Steps

### Step 1: Open Browser Console
1. Open Chrome/Firefox/Safari
2. Press F12 or right-click → "Inspect"
3. Go to "Console" tab
4. Clear existing logs (optional)

### Step 2: Reproduce the Issue
1. Resize browser to mobile size (<768px width)
2. Navigate to a band's library: `/bands/your-band-id`
3. Click "Settings" in bottom navigation
4. Click "Library" in bottom navigation
5. Observe console output

### Step 3: Analyze Debug Output

#### Expected Debug Logs
```
BottomNavBar - Current band ID: "your-band-id" Path: "/bands/your-band-id"
// ... navigation to settings ...
BottomNavBar - Current band ID: "your-band-id" Path: "/bands/your-band-id/settings/members"
Library click - Navigating to band: "your-band-id"
```

#### Common Issues & Solutions

| Console Output | Likely Cause | Solution |
|---------------|-------------|----------|
| `currentBandId: null` | Band context lost | Fix context preservation logic |
| `currentBandId: undefined` | URL parsing failed | Debug matchPath logic |
| No logs at all | Component not rendering | Check routing configuration |
| Wrong band ID | Stale context | Improve context updating |

### Step 4: Check Network Requests
1. Go to "Network" tab in dev tools
2. Filter for `/bands/*` requests
3. Check if band data is being fetched
4. Verify response status codes

### Step 5: Examine React Query Cache
1. In console, type: `window.queryClient.getQueryData(['band', 'your-band-id'])`
2. Check if band data exists in cache
3. Verify data structure matches expectations

### Step 6: Test Direct Navigation
1. Manually navigate to `/bands/your-band-id`
2. Verify page loads correctly
3. Check console for errors
4. Compare with bottom nav behavior

## Common Root Causes

### 1. Band Context Loss
**Symptoms**: `currentBandId: null` in console
**Causes**:
- Navigation resets context
- URL parameters not preserved
- matchPath logic failure

**Fixes**:
```tsx
// Ensure band ID is preserved in navigation state
// Improve URL parameter extraction
// Add fallback handling
```

### 2. Race Conditions
**Symptoms**: Intermittent black screens
**Causes**:
- Data not loaded before render
- Async timing issues
- State update conflicts

**Fixes**:
```tsx
// Add loading states
// Use suspense boundaries
// Implement data fetching guards
```

### 3. Routing Issues
**Symptoms**: Wrong URL or 404 errors
**Causes**:
- Incorrect route paths
- Missing route parameters
- Route configuration errors

**Fixes**:
```tsx
// Verify route definitions
// Check parameter passing
// Add route validation
```

### 4. Component Rendering
**Symptoms**: Component doesn't mount
**Causes**:
- Conditional rendering issues
- Error boundaries catching exceptions
- Missing dependencies

**Fixes**:
```tsx
// Add error boundaries
// Improve error handling
// Verify component imports
```

## Immediate Fixes to Try

### Fix 1: Add Loading State to BandPage
```tsx
// In BandPage.tsx
if (isLoading) return <div>Loading band data...</div>;
if (!band) return <div>Band not found</div>;
```

### Fix 2: Improve Band Context Preservation
```tsx
// In BottomNavBar.tsx
const currentBandId = bandMatch?.params?.bandId || 
                     location.state?.bandId || 
                     localStorage.getItem('currentBandId');
```

### Fix 3: Add Error Boundary
```tsx
// Wrap BandPage with error boundary
<ErrorBoundary fallback={<div>Failed to load band</div>}>
  <BandPage />
</ErrorBoundary>
```

## Debugging Checklist

- [ ] Open browser console
- [ ] Reproduce black screen issue
- [ ] Capture console output
- [ ] Check network requests
- [ ] Examine React Query cache
- [ ] Test direct navigation
- [ ] Identify root cause
- [ ] Implement targeted fix
- [ ] Re-test after fix

## Console Output Template

**Issue Reproduction**:
```
// Paste console logs here
// Include timestamps if possible
// Note any errors or warnings
```

**Network Requests**:
```
// List relevant network requests
// Note status codes and responses
```

**React Query Cache**:
```
// Show cache contents
// Verify data structure
```

**Root Cause Analysis**:
```
// Identified issue:
// Proposed solution:
// Expected outcome:
```

## Support Information

If you need additional help:
1. Share console output
2. Describe exact reproduction steps
3. Note browser and version
4. Include screenshots if helpful

**Contact**: Support team or development lead
**Priority**: High (user-facing issue)
**Impact**: Critical (blocks mobile navigation)