xtremobile/OPTIMIZATION_PLAN.md

# 🚀 PERFORMANCE OPTIMIZATION PLAN - TIVIMATE PARITY

**Goal:** Achieve TiviMate-level performance across all areas
**Date:** March 25, 2026
**Total Issues Found:** 23 issues (3 critical, 6 high, 8 medium, 6 low)

---

## 🎯 QUICK WINS (Hour 1-2)

### P0-1: Fix EPG N+1 Query Storm
**Impact:** 50-200 concurrent requests → 1 bulk request
**File:** `lib/features/iptv/widgets/mobile_live_tv_tab.dart:556`

**Current:** Each channel card calls `getShortEPG()` individually
```dart
// BAD - Fires 50+ concurrent requests
for (Channel channel in channels) {
  final epg = await service.getShortEPG(channel.streamId);
}
```

**Fix:** Batch EPG fetching
```dart
// GOOD - 1 request for all channels
final epgData = await service.getBatchEPG(channelIds);
```

**Expected Impact:** -80% network congestion, -90% jank

---

### P0-2: Remove Destructive Cache Clearing on Startup
**Impact:** 5-20s saved on each app launch
**File:** `lib/main.dart:31`

**Current:** Deletes entire cache on every startup
```dart
await Hive.deleteBoxFromDisk('dio_cache');  // BAD
```

**Fix:** Implement TTL-based invalidation
```dart
// GOOD - Cache lives for 1-6 hours
if (cacheExpired(lastRefresh, duration: Duration(hours: 1))) {
  await refreshCache();
}
```

**Expected Impact:** -80% startup time on cold launches

---

### P0-3: Preserve Tab State with IndexedStack
**Impact:** Instant tab switching, preserved scroll position
**File:** `lib/features/iptv/screens/mobile_dashboard_screen.dart:33`

**Current:** Creates new tab widget on every switch
```dart
// BAD - Tab destroyed, all data lost
switch (currentIndex) {
  case 0: currentTab = MobileLiveTVTab(...); break;
}
```

**Fix:** Use IndexedStack to keep tabs alive
```dart
// GOOD - All tabs stay alive in memory
IndexedStack(
  index: currentIndex,
  children: [
    MobileLiveTVTab(playlist: widget.playlist),
    MobileMoviesTab(playlist: widget.playlist),
    // ...
  ],
)
```

**Expected Impact:** Instant switching, zero data loss

---

## 🔧 CORE FIXES (Hour 2-4)

### P1-1: Debounce Search Input
**Impact:** Eliminate per-keystroke rebuilds
**File:** `lib/features/iptv/widgets/mobile_live_tv_tab.dart:40`

**Current:** setState on every keystroke
```dart
// BAD - Full rebuild on each character
_searchController.addListener(() {
  setState(() { _searchQuery = _searchController.text; });
});
```

**Fix:** Use debounce (500ms)
```dart
// GOOD - Only rebuild after 500ms of inactivity
_searchDebounce = Timer(Duration(milliseconds: 500), () {
  setState(() { _searchQuery = _searchController.text; });
});
```

**Expected Impact:** -95% search-related jank

---

### P1-2: Image Cache Size Limits
**Impact:** -50% memory usage, faster scrolling
**Files:** Multiple `CachedNetworkImage` usage

**Current:** No size limits
```dart
// BAD - Downloads full resolution (could be 1000x1500px)
CachedNetworkImage(imageUrl: url)
```

**Fix:** Set appropriate display sizes
```dart
// GOOD - Resized to 100x150 display size
CachedNetworkImage(
  imageUrl: url,
  memCacheWidth: 100,
  memCacheHeight: 150,
  maxHeightDiskCache: 150,
  maxWidthDiskCache: 100,
)
```

**Expected Impact:** -60% cache size, -40% memory

---

### P1-3: Fix Double FocusNode Disposal
**Impact:** Eliminate crash on player exit
**File:** `lib/features/iptv/screens/native_player_screen.dart:458`

**Current:** Disposes FocusNodes twice
```dart
// BAD - Double disposal causes crash
@override
void dispose() {
  _playPauseFocusNode.dispose();      // First
  // ... more disposals ...
  _playPauseFocusNode.dispose();      // SECOND - CRASH!
  super.dispose();
}
```

**Fix:** Single disposal pass
```dart
// GOOD - Each node disposed once
@override
void dispose() {
  _playPauseFocusNode.dispose();
  _prevFocusNode.dispose();
  _nextFocusNode.dispose();
  _sliderFocusNode.dispose();
  _backFocusNode.dispose();
  _audioFocusNode.dispose();
  super.dispose();  // No duplicate disposals
}
```

---

## 📊 MEDIUM-IMPACT FIXES (Hour 4-6)

### P2-1: Consolidate DNS Resolution
**Impact:** Unified DNS strategy, -50% duplicate resolution
**Files:** `dns_resolver.dart` + `dns_interceptor.dart`

**Current:** Two separate implementations, separate caches
```dart
// BAD - Duplicate implementations, no cache sharing
class DnsResolver { static final _cache = {}; }
class DnsFallbackInterceptor { final _dnsCache = {}; }
```

**Fix:** Single unified DNS service
```dart
// GOOD - Single cache, shared across app
class UnifiedDnsResolver {
  static final _cache = <String, (String, DateTime)>{};

  static String? getCached(String host) {
    final (ip, expires) = _cache[host] ?? (null, DateTime(2000));
    return DateTime.now().isBefore(expires) ? ip : null;
  }
}
```

---

### P2-2: Variable Buffer Size for VOD (Device-Aware)
**Impact:** Prevent OOM on low-end devices
**File:** `lib/features/iptv/screens/native_player_screen.dart:187`

**Current:** Fixed 100MB
```dart
// BAD - 100MB on all devices, 1GB RAM devices crash
_player.setProperty('demuxer-max-bytes', '100000000');
```

**Fix:** Device-aware sizing
```dart
// GOOD - 20MB low-end, 100MB high-end
final maxBytes = device.ram < 2 ? 20000000 : 100000000;
_player.setProperty('demuxer-max-bytes', maxBytes.toString());
```

---

### P2-3: Fix Movies Tab Infinite Retry Loop
**Impact:** Prevent UI freeze on API failures
**File:** `lib/features/iptv/widgets/mobile_movies_tab.dart:225`

**Current:** Retry scheduled on every build
```dart
// BAD - Infinite loop if API fails
if (_categories.isEmpty && !_isLoading) {
  WidgetsBinding.instance.addPostFrameCallback((_) {
    if (mounted && _categories.isEmpty) {
      _loadCategories();  // Retry forever
    }
  });
}
```

**Fix:** Count retries, add exponential backoff
```dart
// GOOD - Max 3 retries with 2s+ delay
if (_categories.isEmpty && !_isLoading && _retryCount < 3) {
  await Future.delayed(Duration(seconds: 2 << _retryCount));
  _loadCategories();
  _retryCount++;
}
```

---

### P2-4: Pause HeroCarousel Auto-Play When Off-Screen
**Impact:** -1 rebuild/sec when carousel invisible
**File:** `lib/core/widgets/components/hero_carousel.dart:42`

**Current:** Always runs
```dart
// BAD - Runs even when user is on another tab
_pageController?.nextPage(
  duration: Duration(seconds: 8),
  curve: Curves.easeInOut,
);
```

**Fix:** Pause when visibility changes
```dart
// GOOD - Only animate when visible
if (_isVisible) {
  _pageController?.nextPage(duration, curve);
}
```

---

## 🧹 CLEANUP FIXES (Hour 6-7)

### P3-1: Disable LogInterceptor in Production
**Impact:** -5% CPU during large downloads
**File:** `lib/core/api/api_client.dart:21`

```dart
// BAD - Logs full request/response on every call
_dio.interceptors.add(LogInterceptor(
  requestBody: true,
  responseBody: true,
));

// GOOD - Disabled in production
if (kDebugMode) {
  _dio.interceptors.add(LogInterceptor(...));
}
```

---

### P3-2: Remove Unused go_router Dependency
**Impact:** -2% bundle size
**File:** `pubspec.yaml:28`

```yaml
# REMOVE this line entirely
go_router: ^13.2.5
```

---

### P3-3: Cancel Clock Stream Properly
**Impact:** -1 rebuild/sec
**File:** `lib/mobile/widgets/mobile_scaffold.dart:30`

```dart
// BAD - Never cancelled, runs forever
_clockStream = Stream.periodic(Duration(seconds: 1));

// GOOD - Cancel on dispose
@override
void dispose() {
  _clockSubscription?.cancel();
  super.dispose();
}
```

---

### P3-4: Declare Color Constants
**Impact:** Minor GC pressure reduction
**Files:** Multiple files

```dart
// BAD - New Color object on every build
Color shade = Colors.blue.withOpacity(0.8);

// GOOD - Declare once
static const Color BUTTON_SHADE = Color.fromARGB(204, 33, 150, 243);
```

---

## 📈 EXPECTED IMPROVEMENTS

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| **Startup Time (cold)** | 15-20s | 3-5s | -75% |
| **Tab Switch Speed** | 1-2s rebuild | <100ms | -95% |
| **Live Tab Channel Load** | 5-8s (50 requests) | <2s (1 request) | -75% |
| **Search Responsiveness** | Jank on each keystroke | Smooth | -99% |
| **Memory Peak** | 600-800MB | 300-400MB | -50% |
| **Cache Size** | Deleted/rebuilt | Persistent | -80% startup |
| **Low-End Device Crashes** | Frequent (OOM) | Rare | -90% |
| **Battery (1h usage)** | 25% drain | 18% drain | -28% |

---

## 🎬 IMPLEMENTATION ORDER

1. **Day 1 (Critical)** - Fix EPG storm, cache clearing, tab state → 80% perceived improvement
2. **Day 2 (High)** - Debounce search, image caching, focus fix
3. **Day 3 (Medium)** - DNS consolidation, buffer sizing, retry loop fix
4. **Day 4 (Low)** - Cleanup: logging, dependencies, streams

---

## ✅ SUCCESS CRITERIA

- [ ] Startup time < 5 seconds (cold)
- [ ] Tab switching instant (<100ms)
- [ ] Live tab loads <2 seconds
- [ ] Search feels snappy (no per-keystroke jank)
- [ ] Memory peak <400MB on typical usage
- [ ] No crashes from player exit
- [ ] Cache persists across launches
- [ ] OOM-free on 2GB RAM devices

---

## 📊 TRACKING

- [ ] EPG N+1 query storm fixed
- [ ] Cache clearing on startup removed
- [ ] Tab state preserved with IndexedStack
- [ ] Search debounced
- [ ] Image cache size limited
- [ ] FocusNode disposal fixed
- [ ] DNS resolution unified
- [ ] Buffer size variable
- [ ] Movies retry loop fixed
- [ ] HeroCarousel auto-play paused when invisible
- [ ] LogInterceptor disabled
- [ ] go_router removed
- [ ] Clock stream cancelled
- [ ] Color constants declared

---

**Next Step:** Start with P0 issues immediately