# Cheatsheet Debug – Plugin `google_cast`

Guida ultra-rapida per capire **subito** dove guardare quando qualcosa non funziona.

---

# 1. Flusso mentale in 10 secondi

```text
UI Flutter
  ↓
cast_controller.dart
  ↓
google_cast_controller.dart / custom_cast_controller.dart
  ↓
MethodChannel('google_cast')
  ↓
FlutterCastFrameworkPlugin.kt
  ↓
CastMediaClient / CastQueueManager / CastCustomReceiver / SessionHandler
  ↓
TV / Chromecast / Custom Receiver
```

---

# 2. Se succede X → apri questi file

## Connessione device non parte
- `lib/widgets/collection/app_bar/cast/cast_icon_button.dart`
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/FlutterCastFrameworkPlugin.kt`
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastDialogLauncher.kt`
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastSessionHandler.kt`

---

## Il device si connette ma non parte nessun media
- `lib/widgets/collection/app_bar/cast/cast_bar_inline.dart`
- `lib/widgets/cast/google_cast_controller.dart`
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastQueueManager.kt`

---

## Google Cast fa `Invalid Request` appena scelgo il device
- `lib/widgets/cast/google_cast_controller.dart`
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastMediaClient.kt`

### Controlla subito:
- polling avviato troppo presto in `onCastReady`
- sessione connessa ma queue ancora vuota

---

## `MediaQueue error 2001`
- `lib/widgets/cast/google_cast_controller.dart`
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastQueueManager.kt`
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastMediaClient.kt`

### Controlla subito:
- queue non caricata davvero
- startIndex invalido
- callback media attiva senza media reale

---

## Slideshow fa prima e seconda foto poi si ferma
- `lib/widgets/cast/google_cast_controller.dart`
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastMediaClient.kt`

### Segnale tipico:
non arriva più `onQueueIndexChanged`

---

## In slideshow un video viene saltato dopo 5 secondi
- `lib/widgets/cast/google_cast_controller.dart`
- `lib/widgets/cast/custom_cast_controller.dart`

### Regola corretta:
- foto → timer
- video → nessun timer, deve finire da solo

---

## In manuale/fullscreen le foto avanzano da sole
- `lib/widgets/cast/google_cast_controller.dart`
- `lib/widgets/cast/custom_cast_controller.dart`

### Regola corretta:
- foto manuali/fullscreen → ferme finché non premi next/prev
- video → a fine video vanno al successivo

---

## `Invalid startIndex: X`
- `lib/widgets/collection/app_bar/cast/cast_bar_inline.dart`
- `lib/widgets/cast/google_cast_controller.dart`
- `lib/widgets/cast/custom_cast_controller.dart`
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastQueueManager.kt`

### Controlla subito:
- `startIndex` più grande di `entries.length - 1`
- indice vecchio riusato su nuova selezione

---

## Seek cambia sulla TV ma non sul telefono
- `lib/widgets/cast/google_cast_controller.dart`
- `lib/widgets/viewer/fullscreen_cast_viewer.dart`

### Controlla subito:
- `seekCast()` aggiorna `positionNotifier`
- `VideoWidget` locale ascolta `positionNotifier` / `isPlayingNotifier`

---

## Il volume compare ma la barra non si aggiorna
- `lib/widgets/cast/google_cast_controller.dart`
- `lib/widgets/collection/app_bar/cast/cast_controls_sheet.dart`
- `lib/widgets/viewer/fullscreen_cast_viewer.dart`
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastMediaClient.kt`

### Controlla subito:
- dopo `setVolume` e `setMute` fai `refreshVolumeStatus()`
- nello slider separa `onChanged` e `onChangeEnd`

---

## Scelgo Google ma sembra partire Custom
- `lib/widgets/collection/app_bar/cast/cast_icon_button.dart`
- `lib/widgets/cast/cast_controller.dart`
- `lib/widgets/cast/custom_cast_controller.dart`
- `lib/widgets/cast/google_cast_controller.dart`

### Controlla subito:
- backend attivo (`_backend`) allineato col backend scelto
- icona Cast solo connect-only
- media avviati solo dalla cast bar

---

## In selection mode la app bar “tocca” anche le foto sotto
- `lib/widgets/collection/app_bar/collection_app_bar.dart`
- `lib/widgets/common/identity/aves_app_bar.dart`
- `lib/widgets/collection/collection_page.dart`

### Controlla subito:
- la barra assorbe i tap?
- è presente `AInkResponse` o equivalente?
- `pinned` + altezza header coerenti col body?

---

## Custom receiver: progress bar duplicate / overlay strani sulla TV
- `lib/widgets/cast/custom_cast_controller.dart`
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastCustomReceiver.kt`
- `receiver.html`
- eventuale JS del receiver

### Controlla subito:
- il DOM viene pulito prima di ridisegnare?
- stai creando un nuovo overlay a ogni update?

---

## Volume Custom non cambia davvero il video
- `lib/widgets/cast/custom_cast_controller.dart`
- `receiver.html`
- JS del receiver

### Controlla subito:
- il receiver gestisce davvero `SET_VOLUME`?
- aggiorna `video.volume`?
- risponde con `VOLUME_STATUS`?

---

# 3. Comando → dove passa

## `showCastDialog`
```text
CastIconButton
→ cast_controller.dart
→ google/custom controller
→ MethodChannel('google_cast')
→ FlutterCastFrameworkPlugin.kt
→ CastDialogLauncher.kt
```

## `loadQueue`
```text
CastBarInline / slideshow / fullscreen
→ cast_controller.dart
→ google_cast_controller.dart
→ MethodChannel('google_cast')
→ FlutterCastFrameworkPlugin.kt
→ CastQueueManager.kt
```

## `play / pause / seekTo`
```text
UI controlli
→ cast_controller.dart
→ google/custom controller
→ MethodChannel('google_cast')
→ FlutterCastFrameworkPlugin.kt
→ CastMediaClient.kt
```

## `setVolume / setMute`
```text
UI volume slider / mute
→ cast_controller.dart
→ google/custom controller
→ MethodChannel('google_cast')
→ FlutterCastFrameworkPlugin.kt
→ CastMediaClient.kt (Google)
oppure
→ receiver custom via JSON (Custom)
```

---

# 4. Evento → da dove torna

## `onCastReady`
```text
CastSessionHandler.kt
→ FlutterCastFrameworkPlugin.kt
→ MethodChannel callback
→ google_cast_controller.dart / custom controller
```

## `onQueueIndexChanged`
```text
RemoteMediaClient.Callback in CastMediaClient.kt
→ Flutter invokeMethod
→ google_cast_controller.dart
```

## `onVideoFinished`
```text
RemoteMediaClient.Callback in CastMediaClient.kt
→ Flutter invokeMethod
→ google_cast_controller.dart
```

## `MEDIA_STATUS` / `VOLUME_STATUS` (Custom)
```text
receiver web
→ messaggio custom
→ plugin Android
→ custom_cast_controller.dart
```

---

# 5. Google vs Custom: differenza operativa

## Google Cast standard
Usa:
- queue nativa Cast
- volume di sessione Cast
- callback `RemoteMediaClient`

### Se qualcosa non va, guarda prima:
- `google_cast_controller.dart`
- `CastMediaClient.kt`
- `CastQueueManager.kt`

---

## Custom Receiver
Usa:
- messaggi JSON custom
- receiver web / CAF
- player HTML5 lato TV

### Se qualcosa non va, guarda prima:
- `custom_cast_controller.dart`
- `CastCustomReceiver.kt`
- `receiver.html`
- JS del receiver

---

# 6. Regole d’oro

## Regola 1
Se la **TV fa la cosa giusta ma il telefono no**:
👉 problema quasi sempre lato Flutter/controller/viewer.

Guarda:
- `google_cast_controller.dart`
- `custom_cast_controller.dart`
- `fullscreen_cast_viewer.dart`

---

## Regola 2
Se **Flutter crede di essere corretto ma la TV fa cose strane**:
👉 problema spesso lato plugin Android o receiver.

Guarda:
- `CastMediaClient.kt`
- `CastQueueManager.kt`
- `CastCustomReceiver.kt`
- receiver JS/HTML

---

## Regola 3
Se il problema nasce **subito dopo la connessione device**:
👉 controlla sempre la distinzione tra:
- sessione Cast pronta
- media davvero caricato

Guarda:
- `CastSessionHandler.kt`
- `google_cast_controller.dart`
- `CastMediaClient.kt`

---

## Regola 4
Se il bug riguarda **selection mode / app bar / tocchi**:
👉 il plugin Cast probabilmente non c’entra.

Guarda:
- `collection_app_bar.dart`
- `aves_app_bar.dart`
- `collection_page.dart`

---

# 7. Checklist rapidissima prima di impazzire

- Hai salvato tutti i file?
- Hai eliminato eventuali backtick markdown rimasti nel file?
- Hai fatto `flutter clean` se i simboli sembrano “mancare” senza senso?
- Il backend attivo è davvero quello giusto?
- Il problema è Flutter-side, Android-side o receiver-side?

---

# 8. Formula finale da ricordare

## **Flutter decide l’UX → il plugin Android parla con Cast → il receiver riproduce davvero**

Quindi ogni bug va classificato subito così:

### A. Flutter / UI
- notifier
- app bar
- selection
- cast bar
- fullscreen viewer

### B. Plugin Android
- sessione
- queue
- callback media
- volume nativo

### C. Receiver
- volume custom
- overlay/progress
- player HTML5
- messaggi custom