docs: documenta la modalità time out e dettaglia tutte le funzioni

- README: sezione Funzionalità riscritta per spiegare in modo completo
  display e controller (layout, punteggio/set, config, cambi, servizio,
  voce, time out/spot, reset/referto, regole partita e amichevole).
- CLAUDE.md: descrizione di toggleTimeout, flag `timeout`, cartella `spot/`,
  endpoint `/spot/list` e nota sull'autoplay con audio in kiosk.

CLAUDE.md

@@ -46,7 +46,9 @@ Punteggio, set e servizio si ricavano sempre dalla `striscia`: al primo punto di
 
 `src/referto.js` genera il referto di gara: `buildRefertoHtml(state, now)` è una funzione pura che restituisce l'HTML (testabile), mentre `generaReferto(state)` è il wrapper che apre la finestra con `window.open` e avvia la stampa.
 
-`src/persist.js` carica/salva lo stato su `.segnapunti/state.json`. `src/server-utils.js` ricava gli IP di rete (`getNetworkIPs`, con sorgente iniettabile) e stampa gli URL all'avvio.
+`src/persist.js` carica/salva lo stato su `.segnapunti/state.json`. `src/server-utils.js` ricava gli IP di rete (`getNetworkIPs`, con sorgente iniettabile) e stampa gli URL all'avvio. `src/spot-utils.js` espone `listSpotVideos(spotDir)`, che elenca i `.mp4` (ordinati) della cartella `spot/`; ritorna `[]` se la cartella manca.
+
+**Time out / spot video** — l'action `toggleTimeout` commuta il flag booleano `state.timeout`. Quando attivo, il display mostra a tutto schermo i video `.mp4` della cartella `spot/` nella root (non versionata): uno solo va in loop, più video girano in sequenza ripartendo dal primo; se la cartella è vuota mostra un overlay "TIME OUT". La lista è esposta dall'endpoint HTTP `/spot/list` (JSON) e i file sono serviti staticamente da `/spot/<file>.mp4`, sia in produzione (`server.js`) sia in sviluppo (`vite-plugin-websocket.js`). I video partono con audio; se il browser blocca l'autoplay con suono si ripiega automaticamente su muto — per avere l'audio reale il browser del display (schermo senza input) va avviato in kiosk con autoplay consentito (es. Chrome `--autoplay-policy=no-user-gesture-required`).
 
 `server.js` (Express) espone `createApp(distDir)` (solo routing, testabile) e `startServer(port)` (HTTP + WebSocket); serve entrambe le interfacce sulla porta 3000: `/display` → `dist/index.html`, `/controller` → `dist/controller.html`. Singolo endpoint WebSocket su `/ws`. L'avvio automatico parte solo se il file è eseguito come entrypoint.
 

README.md

@@ -81,34 +81,88 @@ http://<IP-del-server>:3000/controller
 
 ## Funzionalità
 
-### Display
+Il sistema è composto da due interfacce complementari: il **display** è in sola lettura e mostra al pubblico lo stato della partita; il **controller** è il pannello operatore da cui parte ogni azione. Tutto ciò che l'operatore tocca sul controller si riflette istantaneamente sul display via WebSocket.
 
-- Nomi squadre con indicatore di servizio
+### Display (tabellone pubblico)
-- Punteggio del set corrente (grande, leggibile da lontano)
-- Contatore set vinti
-- Striscia storica punti del set in corso, scorrevole verso destra
-- Modalità formazioni: posizioni dei 6 giocatori in campo
-- Indicatore connessione WebSocket (scompare quando connesso, rosso lampeggiante se disconnesso)
 
-### Controller
+Pagina di sola visualizzazione, pensata per uno schermo grande o un proiettore. Mostra:
 
-- **Punti** — `+1` per casa e ospite, con annullamento dell'ultimo punto
+- **Nomi squadre** con **indicatore di servizio** (l'icona della palla compare accanto alla squadra che sta servendo).
-- **Dialog set vinto** — appare automaticamente al raggiungimento dei 25 punti (o 15 nel tie-break); permette di confermare il set o annullare l'ultimo punto
+- **Punteggio del set corrente** in caratteri molto grandi, leggibili da lontano.
-- **Formazioni** — configura i numeri di maglia; la rotazione avviene automaticamente al cambio palla
+- **Contatore dei set vinti** per ciascuna squadra.
-- **Cambi** — dialog `IN → OUT` con validazione
+- **Striscia storica dei punti** del set in corso: una sequenza scorrevole che ricostruisce l'andamento punto su punto.
-- **Servizio** — cambio manuale (disponibile solo a 0-0)
+- **Modalità formazioni**: in alternativa al punteggio, mostra le posizioni dei 6 giocatori in campo (numeri di maglia disposti come a referto).
-- **Visualizzazione** — alterna tra punteggio grande e formazioni in campo
+- **Ordine di visualizzazione invertibile**: le due squadre possono essere scambiate di lato per rispecchiare l'orientamento reale del campo.
-- **Striscia** — mostra/nasconde lo storico punti sul display
+- **Overlay time out / spot**: durante un time out copre il tabellone con i video della cartella `spot/` (vedi sotto).
-- **Reset** — azzera la partita (richiede conferma)
+- **Annuncio vocale del punteggio** (sintesi vocale del browser), comandato dal controller.
-- **Referto** — a fine partita, dal dialog *PARTITA FINITA*, genera un referto di gara stampabile/PDF (punteggi per set, formazioni di partenza, andamento punto-punto). *Funzione prototipale.*
+- **Indicatore di connessione**: scompare quando tutto è connesso, diventa un punto rosso lampeggiante con scritta *Disconnesso* in caso di problemi.
+- **Fullscreen automatico** all'apertura sui dispositivi mobili.
+
+### Controller (pannello operatore)
+
+Il controller adatta automaticamente il proprio layout all'orientamento del dispositivo:
+
+- **Verticale (smartphone)** — layout compatto: anteprima punteggio toccabile in alto e griglia di pulsanti sotto.
+- **Orizzontale (tablet)** — layout esteso "da regia": due grandi pannelli squadra affiancati con punteggio, campo e tasto set, più una barra di azioni in basso.
+
+#### Gestione del punteggio
+
+- **Punto** — tocca il punteggio/la card di una squadra per assegnarle `+1`. Il sistema gestisce automaticamente il **cambio palla** e la **rotazione** della squadra che riconquista il servizio.
+- **Annulla punto** — rimuove l'ultimo punto assegnato, ripristinando anche eventuale rotazione e servizio.
+- **Tasti SET** — incrementano manualmente il contatore dei set vinti di una squadra (utile per correzioni); il contatore cicla da 0.
+- **Dialog automatico SET VINTO / PARTITA FINITA** — compare da solo al raggiungimento delle condizioni di vittoria (25 punti, o 15 nel set decisivo, con 2 di scarto). Da qui puoi:
+  - **VAI AL SET SUCCESSIVO** — chiude il set, lo registra come vinto e prepara il set successivo aprendo la configurazione delle formazioni;
+  - **INDIETRO** — annulla l'ultimo punto se il dialog è comparso per errore;
+  - a partita conclusa, **REFERTO** per generare il referto e **CHIUDI** per tornare al tabellone.
+
+#### Configurazione partita
+
+Dal pulsante **Config** si apre una finestra che permette di impostare:
+
+- **Nomi delle squadre** (Home e Guest);
+- **Modalità partita**: `2/3` (al meglio dei 3 set), `3/5` (al meglio dei 5 set) o `Amichevole` (senza vittoria automatica della partita);
+- **Formazioni iniziali**: i numeri di maglia dei 6 giocatori in campo per ciascuna squadra, disposti per zona.
+
+#### Cambi giocatore
+
+Il pulsante **Cambi** apre, dopo aver scelto la squadra, un dialog con righe `IN → OUT`. Le sostituzioni vengono **validate** prima di essere applicate: i numeri devono essere cifre, il giocatore entrante non può essere già in campo, quello uscente deve essere effettivamente in formazione, e nessuno può sostituire sé stesso. Eventuali errori sono segnalati in chiaro.
+
+#### Servizio e visualizzazione
+
+- **Cambio Palla** — assegna manualmente il servizio; disponibile **solo a 0-0** (a inizio set).
+- **Inverti** — scambia il lato delle due squadre sul display.
+- **Formazioni / Punteggio** — alterna sul display la vista formazioni in campo e la vista punteggio.
+- **Striscia ON/OFF** — mostra o nasconde lo storico punti del set sul display.
+- **Voce** — fa annunciare al display il punteggio corrente con la sintesi vocale (es. *"15 a 12"*, *"15 pari"*, *"zero a zero"*).
+
+#### Time Out e spot pubblicitari
+
+Il pulsante **Time Out** attiva/disattiva la proiezione degli spot sul display. Quando la modalità è attiva il controller resta **pienamente operativo** ma è chiaramente evidenziato: compare un banner *MODALITÀ TIME OUT ATTIVA* e il pulsante diventa arancione e pulsante. Ripremendolo si esce e il display torna al punteggio.
+
+I video da proiettare vanno messi in una cartella **`spot/`** nella root del progetto (non versionata). Comportamento:
+
+- **un solo** video `.mp4` → riprodotto in loop continuo;
+- **più** video `.mp4` → riprodotti in sequenza in ordine alfabetico, poi si riparte dal primo;
+- **cartella vuota o assente** → il display mostra un overlay nero con la scritta *TIME OUT*.
+
+> **Audio:** i video partono con audio, ma il display è in genere uno schermo senza tastiera/mouse e i browser bloccano l'autoplay con suono senza un'interazione dell'utente. In assenza di configurazione il video parte automaticamente **muto** (il video si vede comunque). Per avere l'audio, avvia il browser del display in modalità kiosk consentendo l'autoplay con suono (es. Chrome con `--autoplay-policy=no-user-gesture-required`, oppure impostando un'eccezione del sito per audio/video).
+
+#### Reset e referto
+
+- **Reset** — azzera la partita (punteggi, set e formazioni) previa conferma, e riapre subito la configurazione per impostare la partita successiva.
+- **Referto** — a fine partita, dal dialog *PARTITA FINITA*, genera un referto di gara stampabile/PDF con i punteggi per set, le formazioni di partenza e l'andamento punto-punto. *Funzione prototipale.*
 
 ### Regole pallavolo integrate
 
+Le condizioni di vittoria del set sono applicate automaticamente dal server (è quello che fa comparire il dialog *SET VINTO*):
+
 | Set | Condizione di vittoria |
 |---|---|
 | Set 1–4 (modalità 3/5) o 1–2 (modalità 2/3) | Primo a **25** con almeno 2 punti di scarto |
 | Set decisivo (tie-break) | Primo a **15** con almeno 2 punti di scarto |
 
+La **partita** è vinta da chi raggiunge 3 set su 5 (modalità `3/5`) o 2 set su 3 (modalità `2/3`). In modalità **Amichevole** non c'è vittoria automatica della partita: si continua a giocare set senza che compaia *PARTITA FINITA*.
+
 ---