Effective collaboration with AI agents

# Ongaku Mobile DIRECT Upgrade Plan - SDK 45 → 53 (No Incremental Steps)

## ⚡ STRATEGY: Direct Jump to Latest Versions WITH New Architecture
**We're going straight from SDK 45 to SDK 53 WITH the New Architecture enabled** - no incremental upgrades, maximum performance. This saves hours of work and gets us the latest stable versions with best performance immediately.

### Why New Architecture?
- **Better Performance**: Direct communication via JSI instead of bridge
- **Faster Startup**: TurboModules load on-demand
- **Type Safety**: Better TypeScript integration
- **Future-Proof**: Legacy architecture is frozen, no new features
- **SDK 53 Default**: It's the default anyway, we're just embracing it

## 📊 Current → Target Versions
| Package | Current | Target | Breaking Changes |
|---------|---------|--------|------------------|
| **expo** | 45.0.0 | **53.0.0** | Major: New Architecture ENABLED, expo-av deprecated |
| **react** | 17.0.2 | **19.0.0** | Automatic batching, stricter types |
| **react-native** | 0.68.2 | **0.79.0** | New Architecture, Metro changes |
| **@react-native-firebase** | 15.4.0 | **23.3.1** | Minor API updates only |
| **@react-navigation** | 6.x | **7.x** | Navigation API changes |
| **@reduxjs/toolkit** | 1.8.5 | **2.x** | Builder syntax required |
| **styled-components** | 5.3.5 | **6.x** | Transient props, no auto-prefixing |
| **expo-av** | 11.2.3 | **DELETE** → **expo-audio 2.0** | Complete API change |
| **TypeScript** | 4.3.5 | **5.x** | Stricter types |

## 🚨 ALL Breaking Changes (45→53)

### Expo SDK Breaking Changes
1. **expo-av completely removed** - Must migrate to expo-audio
2. **New Architecture enabled by default** in SDK 53 (we're keeping it ENABLED)
3. **Push notifications removed from Expo Go** (need dev build)
4. **Metro uses package.json exports** - May break deep imports
5. **Hermes required in Expo Go** (JSC no longer supported)
6. **expo-barcode-scanner removed** - Use expo-camera instead
7. **Constants.manifest deprecated** - Use Constants.expoConfig
8. **sentry-expo deprecated** - Use @sentry/react-native
9. **ProgressBarAndroid/ProgressViewIOS removed** from React Native
10. **Minimum iOS 13.4, Android SDK 23**

### New Architecture Specific Changes
1. **Fabric Renderer**: New UI rendering system
2. **TurboModules**: On-demand native module loading
3. **JSI (JavaScript Interface)**: Direct JS-to-native communication
4. **Bridgeless Mode**: No more async bridge
5. **Hermes Required**: JSC no longer supported in Expo Go

### React 17→19 Breaking Changes
1. **No ReactDOM.render** - Must use createRoot
2. **Automatic batching** - All updates batched
3. **StrictMode runs effects twice** in development
4. **defaultProps deprecated** - Use default parameters
5. **PropTypes removed** - Use TypeScript

### Package-Specific Breaking Changes
- **React Navigation 7**: navigationInChildEnabled required for nested navigation
- **styled-components 6**: No auto vendor prefixing, use transient props ($prefix)
- **Redux Toolkit 2**: Builder callback required for extraReducers
- **Firebase**: Already native ✅ (minimal changes)

## Step 1: Pre-Flight Checklist (5 minutes)
```bash
cd /Users/rmendiola/code/me/ongaku/ongaku-mobile

# CRITICAL: Verify Node version (must be 18+)
node --version  # You have v23.3.0 ✅

# Check for uncommitted changes - MUST be clean
git status

# Create upgrade branch
git checkout -b direct-sdk-53-upgrade
git add -A && git commit -m "Pre SDK 53 upgrade snapshot"

# Save current state for reference
npm list --depth=0 > deps-before.txt
npx jest --listTests > tests-before.txt

# Check for patches that might break
ls -la patches/ 2>/dev/null || echo "No patches (good)"
grep -E "overrides|resolutions" package.json || echo "No overrides (good)"
```

## Step 2: Nuclear Clean (2 minutes)
```bash
# Stop everything
watchman watch-del-all 2>/dev/null || true
kill $(lsof -t -i:8081) 2>/dev/null || true
kill $(lsof -t -i:19000) 2>/dev/null || true

# Delete EVERYTHING
rm -rf node_modules
rm -rf ios/Pods ios/build
rm -rf android/build android/app/build android/.gradle
rm -rf $HOME/.gradle/caches/
rm package-lock.json yarn.lock
rm -rf .expo
rm -rf $TMPDIR/metro-* $TMPDIR/haste-*

# Clear all caches
npm cache clean --force
cd ios && pod cache clean --all 2>/dev/null || true && cd ..
```

## Step 3: Direct SDK 53 Upgrade with New Architecture (10 minutes)
```bash
# Install latest Expo CLI
npm install -g expo@latest

# DIRECT upgrade to SDK 53 (New Architecture is default)
npx expo upgrade 53

# This will update:
# - expo to ~53.0.0
# - react to ^19.0.0
# - react-native to 0.79.x
# - All expo packages to SDK 53 compatible versions

# Install with force (React 19 has peer conflicts)
npm install --force

# Install missing/updated packages
npx expo install expo-audio@~2.0.0
npm uninstall expo-av  # Remove deprecated package

# Update other major packages to latest
npm install @react-navigation/native@^7.0.0 \
          @react-navigation/bottom-tabs@^7.0.0 \
          @react-navigation/native-stack@^7.0.0 \
          @reduxjs/toolkit@^2.0.0 \
          styled-components@^6.0.0 \
          @react-native-firebase/app@latest \
          @react-native-firebase/analytics@latest \
          --force

# Update dev dependencies
npm install --save-dev @types/react@^19.0.0 \
                     @types/react-native@^0.79.0 \
                     typescript@^5.0.0 \
                     --force
```

## Step 4: Fix Breaking Code Changes & New Architecture Compatibility (20 minutes)

### 4.0: Verify New Architecture Compatibility
```bash
# Check if any code uses direct bridge access (unlikely in this app)
grep -r "NativeModules" --include="*.ts" --include="*.tsx" --include="*.js" . || echo "No direct NativeModules usage (good)"
grep -r "requireNativeComponent" --include="*.ts" --include="*.tsx" --include="*.js" . || echo "No custom native components (good)"
```

### 4.1: Audio Migration (CRITICAL)
```typescript
// File: /Users/rmendiola/code/me/ongaku/ongaku-mobile/logic/playback.ts
// REPLACE ENTIRE FILE with new expo-audio implementation:

import { Audio, AudioPlayer } from 'expo-audio';
import { pitchesToPitchFiles } from './pitchesToPitchFiles';
import { store } from '../redux/store';
import {
addPlayingPitch,
removePlayingPitch,
setPlayingChord,
clearPlayback,
} from '../redux/playbackSlice';
import { PitchFile } from '../constants/piano';

const audioPlayers: Record<string, AudioPlayer> = {};

export const playPitch = async (pitchFile: PitchFile) => {
const { playbackSource, pitch } = pitchFile;

try {
  let player = audioPlayers[pitch];

  if (!player) {
    // Create new player
    player = new AudioPlayer({
      source: playbackSource,
      shouldCorrectPitch: false,
      volume: 1.0,
    });

    // Listen for completion
    player.addListener('playbackStatusUpdate', (status) => {
      if (status.isLoaded && status.didJustFinish) {
        store.dispatch(removePlayingPitch({ pitch }));
        // Reset for replay
        player.seekTo(0).catch(() => {});
      }
    });

    audioPlayers[pitch] = player;
  } else {
    // Reset if replaying
    await player.seekTo(0);
  }

  store.dispatch(addPlayingPitch({ pitch }));
  await player.playAsync();

} catch (error) {
  console.error('Error playing pitch:', pitch, error);
  store.dispatch(removePlayingPitch({ pitch }));
}
};

export const playChord = async (
chord: string,
pitches: string[],
arpeggio: boolean = false
) => {
store.dispatch(clearPlayback());
store.dispatch(setPlayingChord({ chord, pitches, arpeggio }));

const pitchFiles = pitchesToPitchFiles(pitches);

if (arpeggio) {
  for (let i = 0; i < pitchFiles.length; i++) {
    await playPitch(pitchFiles[i]);
    if (i < pitchFiles.length - 1) {
      await new Promise(resolve => setTimeout(resolve, 100));
    }
  }
} else {
  await Promise.all(pitchFiles.map(playPitch));
}
};

export const stopAllSounds = async () => {
await Promise.all(
  Object.values(audioPlayers).map(p => p.pauseAsync().catch(() => {}))
);
store.dispatch(clearPlayback());
};

export const cleanupAudio = async () => {
await Promise.all(
  Object.values(audioPlayers).map(p => p.release().catch(() => {}))
);
Object.keys(audioPlayers).forEach(key => delete audioPlayers[key]);
};
```

### 4.2: Fix Music Theory Test
```typescript
// File: /Users/rmendiola/code/me/ongaku/ongaku-mobile/logic/stepsToIntervals.tsx
// FIX: Return n-1 intervals for n notes

export const stepsToIntervals = (steps: number[]): string[] => {
const intervals: string[] = [];

// Bug fix: Only iterate to length-1
for (let i = 0; i < steps.length - 1; i++) {
  const interval = steps[i + 1] - steps[i];
  intervals.push(INTERVALS[interval] || `+${interval}`);
}

return intervals; // Now returns 3 intervals for 4-note chord
};
```

### 4.3: React Navigation 7 Updates
```typescript
// If you have any navigation.navigate to nested screens:
// OLD: navigation.navigate('ScreenInNestedNavigator')
// NEW: Add to NavigationContainer if needed:
<NavigationContainer navigationInChildEnabled>
{/* your navigators */}
</NavigationContainer>
```

### 4.4: styled-components 6 Updates
```typescript
// Check for any $as or $forwardedAs props:
// OLD: <StyledComponent $as="button" />
// NEW: <StyledComponent as="button" />

// For vendor prefixing (if needed for old browsers):
import { StyleSheetManager } from 'styled-components';

// Wrap your app:
<StyleSheetManager enableVendorPrefixes>
<App />
</StyleSheetManager>
```

### 4.5: Redux Toolkit 2 Updates
```typescript
// Check any createSlice files for object syntax in extraReducers
// OLD: extraReducers: { [action.type]: reducer }
// NEW: Must use builder callback:
extraReducers: (builder) => {
builder.addCase(action, reducer);
}
```

### 4.6: Remove Deprecated Patterns
```bash
# Find and fix deprecated patterns
grep -r "defaultProps" components/ screens/ logic/ || echo "No defaultProps (good)"
grep -r "PropTypes" components/ screens/ logic/ || echo "No PropTypes (good)"
grep -r "Constants.manifest" . || echo "No manifest usage (good)"
grep -r "sentry-expo" . || echo "No sentry-expo (good)"
```

## Step 5: Update app.json Configuration (2 minutes)
```json
// File: /Users/rmendiola/code/me/ongaku/ongaku-mobile/app.json
{
"expo": {
  // ... existing config ...

  // Enable New Architecture (it's default in SDK 53 anyway):
  "experiments": {
    "newArchEnabled": true  // ENABLED for best performance
  },

  // Remove if present:
  // "hooks": { ... }  // Removed in SDK 51

  // Update iOS config (merge with existing ios section):
  "ios": {
    // ... existing config ...
    "deploymentTarget": "13.4",  // Minimum for SDK 53
    // For audio background playback (if needed):
    "infoPlist": {
      "UIBackgroundModes": ["audio"]
    }
  }
}
}
```

## Step 6: Rebuild Native Projects (5 minutes)
```bash
# Clean prebuild with new configuration
npx expo prebuild --clean --npm

# iOS specific fixes
cd ios
# Remove Flipper if present
sed -i '' '/:flipper_configuration/d' Podfile 2>/dev/null || true
# Update pods
pod install --repo-update
cd ..

# Android specific fixes
cd android
# Clean gradle
./gradlew clean
./gradlew --stop
# Enable New Architecture
grep "newArchEnabled" gradle.properties || echo "newArchEnabled=true" >> gradle.properties
# If it exists but is false, update it:
sed -i '' 's/newArchEnabled=false/newArchEnabled=true/g' gradle.properties 2>/dev/null || true
cd ..
```

## Step 7: Verify New Architecture & Everything Works (10 minutes)
```bash
# 1. Run doctor to check for issues (including New Architecture compatibility)
npx expo-doctor

# 2. Verify New Architecture is enabled
grep "newArchEnabled" android/gradle.properties  # Should show: newArchEnabled=true
grep "newArchEnabled" app.json  # Should show: "newArchEnabled": true

# 3. Check critical dependencies installed correctly
npm list expo react react-native @react-native-firebase/app expo-audio

# 4. Start Metro to test basic functionality
npx expo start --clear
# Press 'i' for iOS or 'a' for Android to test

# 5. Run tests
npm test -- --watchAll=false 2>&1 | tee test-results.txt

# 6. Check for deprecation warnings
npx expo start 2>&1 | grep -i "deprecated" || echo "No deprecations!"
```

## Step 8: Manual Testing Checklist
- [ ] App launches without crash (with New Architecture)
- [ ] Verify in logs: "Fabric" and "TurboModule" messages appear
- [ ] Play single note (tests expo-audio)
- [ ] Play chord (tests multiple audio)
- [ ] Play arpeggio (tests sequential audio)
- [ ] Change root note (tests state management)
- [ ] Navigate between screens (tests React Navigation 7)
- [ ] Check Firebase events in console
- [ ] Verify styled-components rendering correctly

## 🚫 Common Issues & Immediate Fixes

### New Architecture Specific Issues

#### Issue: "Library X doesn't support New Architecture"
```bash
# Most libraries work with interop layer in SDK 53
# If a library truly doesn't work, it likely needs updating:
npm list [problematic-package]
# Check for updates:
npm outdated [problematic-package]
# Update to latest:
npm install [problematic-package]@latest --force
```

#### Issue: Performance seems worse
```bash
# This is usually due to development mode
# Test in production mode:
npx expo start --no-dev --minify
# Or build a production version:
eas build --platform ios --profile preview
```

### Issue: "Cannot find module 'expo-av'"
```bash
# You forgot to update imports
grep -r "expo-av" --include="*.ts" --include="*.tsx" --include="*.js"
# Replace all with 'expo-audio'
```

### Issue: Metro "Unable to resolve module"
```bash
rm -rf $TMPDIR/metro-* $TMPDIR/haste-*
npx expo start --clear
```

### Issue: "Peer dependency conflicts"
```bash
npm install --force
# or if that fails:
npm install --legacy-peer-deps
```

### Issue: iOS build fails with pod errors
```bash
cd ios
pod deintegrate
rm -rf ~/Library/Caches/CocoaPods
pod install --repo-update
cd ..
```

### Issue: Android build fails
```bash
cd android
rm -rf ~/.gradle/caches/
./gradlew clean
./gradlew --stop
cd ..
npx expo prebuild --clean
```

### Issue: TypeScript errors
```bash
# Update tsconfig.json
npx tsc --init  # Generate fresh config
# Or just fix errors shown by:
npx tsc --noEmit
```

### Issue: New Architecture specific errors
```bash
# "TurboModules are enabled, but mTurboModuleRegistry hasn't been set"
# Fix: Clean and rebuild
rm -rf ios/build/generated
cd ios && pod install && cd ..
npx expo prebuild --clean

# "Fabric renderer not found"
# Fix: Ensure Hermes is enabled (it should be by default)
grep "hermesEnabled" android/gradle.properties || echo "hermesEnabled=true" >> android/gradle.properties
```

## ✅ Success Validation
```bash
# All of these should pass:
npx expo-doctor                     # ✓ No issues
npm test -- --watchAll=false        # ✓ Tests pass (except known issues)
npx expo start --no-dev --minify    # ✓ Production build works
```

## 🔄 Emergency Rollback
```bash
# If everything breaks:
git checkout main
git branch -D direct-sdk-53-upgrade
rm -rf node_modules ios/Pods android/build
npm install
npx expo prebuild --clean

# You're back to SDK 45
```

## Time Estimate
- **Total: 45-60 minutes** for complete upgrade
- Step 1-2: 7 minutes (cleanup)
- Step 3: 10 minutes (installation)
- Step 4: 20 minutes (code fixes)
- Step 5-6: 7 minutes (configuration)
- Step 7-8: 10 minutes (verification)

## Notes
- **NO incremental upgrades** - We go directly to SDK 53
- **New Architecture ENABLED** - Maximum performance, it's the future
- **expo-audio is simpler** than expo-av - fewer features but more stable
- **Keep native folders** - You have Firebase configuration there
- **React 19 is stricter** - May need to fix more TypeScript errors
- **75% of SDK 52+ apps** already use New Architecture successfully

## styled-components Migration (v5 → v6)

Files: components/PianoKey.tsx, components/ChordDisplay.tsx, screens/HomeScreen.tsx

### 1. Update transient props

3 components pass custom props to styled() wrappers without the $ prefix. In v6, these leak to the DOM and cause React warnings.

```tsx
// components/PianoKey.tsx (lines 45-62)
// Before:
const Key = styled.TouchableOpacity<{ isActive: boolean }>`
background: ${props => props.isActive ? '#fff' : '#000'};
`;
<Key isActive={playing} />

// After:
const Key = styled.TouchableOpacity<{ $isActive: boolean }>`
background: ${props => props.$isActive ? '#fff' : '#000'};
`;
<Key $isActive={playing} />
```

Same pattern for `isPlaying` in ChordDisplay.tsx (line 28) and `highlightColor` in HomeScreen.tsx (line 91).

### 2. Update ThemeProvider import

v6 moves ThemeProvider to a separate entry point for React Native.

```tsx
// App.tsx (line 4)
// Before:
import { ThemeProvider } from 'styled-components';

// After:
import { ThemeProvider } from 'styled-components/native';
```

### Validation
```bash
npx tsc --noEmit && npm test -- --grep "styled"
```