@ing.jorgeu/wargaming-overlay 2.3.0 → 2.5.0

package/PUBLISHING.md

@@ -1,35 +1,28 @@
-# Preparación para npm
+# Publicación de releases
 
-La versión 2.1.0 está empaquetada para distribución, pero NO se ha publicado ni instalado globalmente en el equipo del usuario.
+Paquete: `@ing.jorgeu/wargaming-overlay`, cuenta npm `ing.jorgeu`. Repositorio: https://github.com/ing-jorgeu/wargaming-overlay. Código bajo 0BSD; las notas de recursos visuales están en `THIRD_PARTY_ASSETS.md`.
 
-## Pendiente de decidir
-
-- Nombre elegido: `@ing.jorgeu/wargaming-overlay`. Publicar con la cuenta npm `ing.jorgeu`, confirmada por el titular.
-- Licencia del código resuelta: **0BSD**, seleccionada por el usuario. Permite uso comercial, modificación y redistribución sin atribución obligatoria. Las imágenes requieren revisión por separado.
-- Revisar la procedencia y permiso de redistribución de los recursos visuales; ver `THIRD_PARTY_ASSETS.md`.
-- Añadir `repository`, `homepage`, `bugs` y `author` cuando se conozcan. No se han inventado datos personales ni URLs.
-- Ejecutar el workflow de GitHub Actions en las tres plataformas y probar USB real en Windows y Linux. Aquí solo se validó macOS físicamente; las ramas de otras plataformas se prueban con escenarios simulados.
-
-## Primera publicación manual
-
-Desde la raíz del proyecto, ya con las decisiones anteriores resueltas:
+Desde la raíz del repositorio:
 
 ```sh
+npm ci
+npm version 2.5.0 --no-git-tag-version
 npm test
 npm pack --dry-run
 npm login
 npm whoami
-npm view @ing.jorgeu/wargaming-overlay name version
 npm publish --dry-run
-npm publish --access public
 ```
 
-Si el nombre existe y no eres su propietario, cambia `name` a `@tu-scope/wargaming-overlay` (sustituyendo el ejemplo por un scope real). Consulta el nombre elegido con `npm view` antes de publicar. Un 404 puede significar que el nombre no existe; otros errores no prueban disponibilidad. Usa una versión nueva si ya fue publicada.
+Usa una versión nueva en cada release. Revisa el diff, crea el commit y súbelo a `origin/main` antes de publicar. Después:
 
-El último comando publica realmente. No se ha ejecutado. La autenticación y la verificación de npm deben completarse en tu sesión; no guardes tokens en el repositorio.
+```sh
+npm publish --access public
+npm view @ing.jorgeu/wargaming-overlay version
+```
 
-`prepublishOnly` ejecuta las pruebas. `files` limita el paquete a código, interfaz y documentación; no incluye estado personal, backups, pruebas ni workflows. No hay scripts de instalación automáticos. ADB se instala únicamente al invocar `setup --install-adb`.
+`prepublishOnly` ejecuta las pruebas. npm puede pedir autorización en el navegador tanto para login como para publicar; no guardes tokens en el repositorio. Confirma que el registro muestra la versión esperada y que el commit está en remoto.
 
-Para releases posteriores se puede configurar Trusted Publishing con GitHub Actions desde la configuración del paquete en npm. No se ha creado un workflow de publicación con repositorio o identidad inventados.
+`files` limita el paquete a código, interfaz y documentación. No incluye Excel de investigación, credenciales OAuth, estados de partidas, pruebas ni workflows. Las dependencias de gRPC se instalan por npm; no hay scripts de instalación propios. ADB se instala únicamente al invocar `setup --install-adb`.
 
-Fuentes oficiales: [npm publish](https://docs.npmjs.com/cli/v7/commands/npm-publish/), [Trusted Publishing](https://docs.npmjs.com/trusted-publishers/).
+Las pruebas automatizadas cubren el transporte gRPC local, OAuth simulado y continuidad del overlay ante errores. El acceso real a la API del canal ya se verificó; la recepción de mensajes de un directo y el cambio físico de salida de audio siguen requiriendo una prueba real. Windows/Linux no usan el TTS nativo de macOS.

package/README.md

@@ -354,13 +354,49 @@ Con otra relación de aspecto mantiene 16:9, centrado horizontalmente y alineado
 | `wargaming-overlay setup --dry-run` | Muestra el plan sin instalar ni consultar ADB. |
 | `wargaming-overlay setup --install-adb` | Instala ADB si falta y hay un gestor compatible; después diagnostica. |
 | `wargaming-overlay migrate CARPETA` | Copia el estado anterior sin sobrescribir archivos existentes. |
-| `wargaming-overlay --help` | Muestra ayuda. |
+| `wargaming-overlay youtube-auth --client-secret RUTA` | Autoriza el canal con el JSON OAuth de escritorio. |
+| `wargaming-overlay youtube-auth` | Reautoriza usando el cliente OAuth guardado. |
+| `wargaming-overlay --help` o `-h` | Muestra ayuda. |
 | `wargaming-overlay --version` | Muestra versión. |
 
 `setup --install-adb` usa Homebrew, WinGet, apt-get, dnf o pacman según la plataforma. No instala Node, Python ni gestores de paquetes; no activa opciones de Android, no acepta autorizaciones USB ni acuerdos por ti. Puede pedir permisos del sistema. Si termina instalando pero todavía no detecta ADB, abre otra terminal y ejecuta `doctor`.
 
 `doctor` y `setup` devuelven código 1 si el diagnóstico no está listo, incluso si solo falta conectar el teléfono. Con ADB/Python instalados, `start` conserva el panel abierto y reintenta aunque falte el teléfono.
 
+### Comandos desde el repositorio
+
+Instala las dependencias con `npm ci` (o `npm install` si actualizas dependencias). Todos los comandos de la tabla anterior pueden ejecutarse como `node cli.js COMANDO` sin instalación global.
+
+| Comando | Acción |
+| --- | --- |
+| `npm start` | Inicia el backend desde este checkout. |
+| `npm start -- --port 8766 --interval 5` | Pasa opciones al backend; el separador `--` es necesario. |
+| `npm test` | Ejecuta las pruebas automatizadas; no necesita el canal ni reproduce audio. |
+| `npm run test-tts` | Reproduce tres mensajes de prueba por la salida predeterminada de macOS. |
+| `npm run facts:coverage` | Informa la cobertura real de curiosidades por facción. |
+| `npm run facts:coverage -- --require-four-hours` | Devuelve código 1 si alguna facción no llega a 120 curiosidades. |
+| `npm run prepublishOnly` | Ejecuta las pruebas previas a publicar; npm lo invoca automáticamente en `npm publish`. |
+| `npm pack --dry-run` | Revisa los archivos que incluirá el paquete sin publicarlo. |
+
+Para instalar o actualizar el comando global: `npm install -g @ing.jorgeu/wargaming-overlay`. Para una versión concreta: `npm install -g @ing.jorgeu/wargaming-overlay@2.5.0`. Usa `wargaming-overlay --version` para comprobar qué instalación ejecuta tu terminal.
+
+### Activar y desactivar la voz de YouTube (macOS)
+
+```sh
+# Desde el repositorio
+YOUTUBE_CHAT_TTS_ENABLED=true npm start
+
+# Con el paquete instalado globalmente
+YOUTUBE_CHAT_TTS_ENABLED=true wargaming-overlay start
+
+# Desactivar explícitamente
+YOUTUBE_CHAT_TTS_ENABLED=false wargaming-overlay start
+```
+
+La variable se aplica a ese inicio. También puedes exportarla en tu terminal; para quitar un valor exportado, usa `unset YOUTUBE_CHAT_TTS_ENABLED`. La configuración opcional `youtube-tts.json`, los pasos OAuth y las limitaciones están en [YouTube Live → voz local](#youtube-live--voz-local-macos). `Ctrl+C` detiene lector, chat y voz; los cambios de código/configuración requieren reiniciar.
+
+Para publicar una release, consulta [PUBLISHING.md](PUBLISHING.md): `npm version VERSION --no-git-tag-version`, `npm login`, `npm whoami`, `npm publish --dry-run` y `npm publish --access public`. La publicación requiere acceso a la cuenta propietaria y una versión no publicada.
+
 ### Opciones
 
 | Opción | Valor predeterminado | Uso |
@@ -371,6 +407,7 @@ Con otra relación de aspecto mantiene 16:9, centrado horizontalmente y alineado
 | `--adb` | Autodetección | Ruta al ejecutable ADB para `start`, `doctor` o `setup`. |
 | `--python` | Autodetección | Ruta al ejecutable Python para `start`, `doctor` o `setup`. |
 | `--data-dir` | Según el sistema | Carpeta de datos para `start` y destino de `migrate`. |
+| `--client-secret` | Cliente guardado, si existe | Ruta al JSON OAuth de escritorio; solo para `youtube-auth`. |
 
 Las opciones no se guardan como configuración del CLI: repítelas en futuros inicios si quieres mantener un puerto, serial o ruta distintos.
 
@@ -461,7 +498,7 @@ El botón **Restablecer datos de la partida** vacía los puntos y misiones guard
 
 Solo lee lo visible. Un bloque sin nombre de jugador se ignora para evitar asignaciones incorrectas. Los datos conservados pueden haber cambiado fuera de pantalla y las listas de misiones pueden ser parciales. No interpreta una lista ausente como lista vacía.
 
-Al cambiar de ronda no reutiliza CP ni misiones de la ronda anterior. Si consultas una ronda histórica en el teléfono, mostrará esa ronda. TOP/BOTTOM se infiere automáticamente al observar aumentos de puntuación o cambios de objetivos previamente leídos. No requiere seleccionar el turno en el panel. El orden se aprende a partir de la primera actividad observada tras una ronda nueva, o desde una partida observada en ronda 1 con ambos marcadores en cero. Si conectas a mitad de partida, puede quedar sin indicar hasta la siguiente ronda. La detección se guarda al reiniciar y es independiente del intercambio de lados. Es una estimación: puntos registrados fuera de turno o correcciones al alza pueden confundirla. No interpreta misiones que aparecen por primera vez al desplazar la pantalla como cartas recién robadas. Bajar puntos o gastar CP no cambia el turno; cambios simultáneos en ambos jugadores lo conservan. El nombre general de la primaria no siempre está expuesto; se muestran sus condiciones de puntuación.
+Al avanzar a la ronda siguiente conserva las secundarias sin puntuar hasta confirmar la lista actual y mantiene las condiciones de primaria, reiniciando sus marcas y contadores. Los totales acumulados se conservan; los CP conservan el último valor leído hasta que el teléfono los actualice. Las lecturas parciales no eliminan misiones fuera de pantalla. No arrastra misiones al consultar rondas anteriores o saltar varias rondas. Si consultas una ronda histórica en el teléfono, mostrará esa ronda. TOP/BOTTOM se infiere automáticamente al observar una secundaria nueva sin puntos que aparece después de la lectura inicial, incluso en listas parcialmente visibles. No requiere seleccionar el turno en el panel. El orden se toma de Tabletop Battles: el primer jugador de la interfaz juega TOP y el segundo BOTTOM. Aunque conectes en ronda 5, la siguiente secundaria nueva permite identificar la mitad sin esperar otra ronda. La primera lectura por sí sola no determina el turno activo; hasta identificarlo se muestra solo la ronda. El último turno identificado se conserva dentro de esa ronda, incluso al cambiar de pantalla o reiniciar. La detección se guarda al reiniciar y es independiente del intercambio de lados. Es una estimación: la lectura parcial puede ocultar cuándo se robó una carta. Recuerda las cartas vistas por jugador y ronda para no confundir su reaparición al desplazar la pantalla con un robo. Una carta sin puntos nunca vista antes puede ser una carta antigua que estaba fuera de pantalla: en ese caso la estimación puede adelantarse. Puntuar primarias o secundarias, marcar objetivos y gastar o ganar CP no cambia el turno; nuevas cartas simultáneas de ambos jugadores conservan el turno anterior. El nombre general de la primaria no siempre está expuesto; se muestran sus condiciones de puntuación.
 
 ## Solución de problemas
 
@@ -625,3 +662,69 @@ npm run facts:coverage -- --require-four-hours
 ```
 
 Al ampliar `data/faction-facts.json`, usa el nombre exacto del registro, conserva los IDs existentes para respetar el historial y asigna un ID estable a cada nueva curiosidad. Incluye un enlace específico, título de fuente y fecha de revisión. No añadas reformulaciones del mismo dato para aumentar artificialmente la duración.
+
+### Continuidad entre USB y Wi-Fi
+
+El lector recuerda el teléfono por su identificador físico en `phone-connection.json`, dentro de la carpeta de datos. Si ADB presenta USB y Wi-Fi para ese mismo teléfono, el overlay prefiere USB. Al retirar el cable, utiliza la conexión inalámbrica autorizada; al reconectarlo, vuelve a USB. Nunca elige otro teléfono por compartir el modelo o una dirección IP anterior.
+
+Activa la depuración inalámbrica y empareja el computador con el teléfono en Android. Tener activada la opción no equivale a estar emparejado. ADB debe poder descubrir el teléfono en la red. Si el descubrimiento no funciona, conecta previamente con `adb connect IP:PUERTO` usando la dirección que Android muestra en Depuración inalámbrica. El overlay puede recuperar direcciones conocidas y servicios inalámbricos que anuncien el identificador del teléfono guardado; no activa puertos de depuración ni empareja dispositivos desconocidos automáticamente.
+
+Para elegir otro teléfono, inicia con `--serial SERIAL` usando su identificador de `adb devices -l`. Si hay varios teléfonos diferentes y ninguno seleccionado, el lector pide seleccionar uno. El panel distingue conexión USB, Wi-Fi y espera de una ronda legible. Al enviar Tabletop Battles al fondo se conserva el último marcador; al volver a la ronda, la lectura se reanuda. Durante una reconexión puede haber una pausa de unos segundos.
+
+## YouTube Live → voz local (macOS)
+
+Función opcional del mismo backend, independiente de OBS y del teléfono. Usa OAuth de solo lectura, descubre el directo activo de la cuenta autorizada y recibe el chat por `liveChatMessages.streamList` (gRPC). La voz sale por el dispositivo predeterminado de macOS; volumen y salida se cambian en macOS. No usa TTS externo ni IA.
+
+### Primera autorización
+
+1. Crea un proyecto en [Google Cloud](https://console.cloud.google.com/) y habilita **YouTube Data API v3**.
+2. Configura Google Auth Platform, añade tu cuenta como usuario de prueba si corresponde y crea un cliente OAuth **Aplicación de escritorio**. Descarga el JSON fuera del repositorio.
+3. Desde este repositorio, ejecuta:
+
+```sh
+node cli.js youtube-auth --client-secret "$HOME/Downloads/client_secret.json"
+```
+
+Con el paquete instalado, el equivalente es `wargaming-overlay youtube-auth --client-secret /ruta/al/archivo.json`. Se abre el navegador: elige la cuenta/canal correcto y concede lectura. El retorno escucha temporalmente solo en `127.0.0.1`, valida `state` y usa PKCE. No se deben pegar tokens en la terminal ni en el chat.
+
+Esta V1 guarda cliente OAuth y tokens en `~/.config/wargaming-overlay/youtube/`, archivos con permisos `0600`, fuera del repositorio y de los recursos HTTP del overlay. El refresh token se reutiliza al reiniciar y renueva el acceso automáticamente. Para desconectar la cuenta, detén el backend, revoca el acceso en tu cuenta Google y elimina esa carpeta. No hay almacenamiento en Keychain en esta versión.
+
+**Google limita a siete días los refresh tokens de proyectos externos en modo Testing** para estos permisos. Antes de usarlo permanentemente, revisa el estado de publicación del proyecto. Una revocación o expiración requiere repetir `youtube-auth`; no se puede garantizar una autorización eterna.
+
+### Arranque y prueba
+
+```sh
+YOUTUBE_CHAT_TTS_ENABLED=true npm start
+npm run test-tts
+```
+
+La segunda instrucción ejecuta tres mensajes falsos, sin YouTube ni OBS. No la ejecutes a la vez que otro lector TTS: la exclusión de voces es por proceso. Para desactivar el chat, omite la variable o usa `YOUTUBE_CHAT_TTS_ENABLED=false`. No se inicia ninguna conexión YouTube cuando está desactivado. En Windows/Linux el overlay continúa pero esta voz no se inicia.
+
+Si no hay directo con chat, comprueba cada 60 segundos. Al conectar omite el historial anterior a la conexión. Mantiene en memoria el identificador del chat, el cursor de continuación y hasta 1.000 IDs recientes. Ante una desconexión reintenta a 1, 2, 5, 10 y como máximo 30 segundos; una única conexión por instancia. Al terminar el directo o deshabilitarse el chat cancela la voz pendiente y vuelve a buscar. Si hay varios directos simultáneos, elige el primero por ID y lo indica en el log.
+
+Los mensajes normales se transforman en eventos `youtube_chat_message`; los eventos administrativos, Super Chat y membresías no se leen en V1. No se escriben mensajes en disco. La terminal muestra mensajes sanitizados y estados YouTube/TTS, sin tokens. Los fallos de OAuth, chat o voz no detienen el overlay.
+
+### Ajustes sencillos
+
+Opcionalmente crea `youtube-tts.json` dentro de la carpeta de datos que muestra el backend al iniciar:
+
+```json
+{
+  "enabled": true,
+  "maxMessageLength": 300,
+  "maxQueueLength": 10,
+  "readUsername": true,
+  "filterUrls": true,
+  "extraBlockedTerms": []
+}
+```
+
+Reinicia el backend para aplicar cambios. Los mensajes se truncan sin cortar palabras cuando es posible, los nombres se limitan a 40 caracteres y las URLs se sustituyen por «Enlace». Si la cola está llena, elimina el pendiente más antiguo; nunca interrumpe una voz para superponer otra. Al detener el backend cancela la voz activa y descarta los pendientes. Cada mensaje usa un proceso nuevo de `/usr/bin/say`, sin shell, sin seleccionar dispositivo, y con un tiempo máximo de 120 segundos.
+
+La moderación es un filtro local pequeño de patrones ES/EN para insultos discriminatorios graves, amenazas directas, llamados a violencia y algunas expresiones sexuales explícitas. Sustituye los fragmentos por «censurado» y descarta mensajes sin contenido restante. Conserva groserías coloquiales como «qué mierda de tirada» o «ese weón tuvo demasiada suerte». **No entiende contexto ni garantiza detectar todas las variantes o idiomas**; amplía `extraBlockedTerms` según el canal. También filtra los nombres y elimina instrucciones de voz embebidas antes de ejecutar `say`.
+
+### Verificación
+
+`npm test` incluye OAuth con callback local y renovación simulada, gRPC local real, descubrimiento de directos, continuación tras desconexión, duplicados, fin del directo, backoff, sanitización y cola sin superposición. No requiere credenciales ni envía mensajes a YouTube. La prueba real de autorización, recepción de un directo y cambio físico de salida de audio requiere la cuenta del canal y comprobación del operador.
+
+Referencias oficiales: [OAuth de escritorio](https://developers.google.com/youtube/v3/guides/auth/installed-apps), [descubrimiento de directos](https://developers.google.com/youtube/v3/live/docs/liveBroadcasts/list), [chat por streaming](https://developers.google.com/youtube/v3/live/streaming-live-chat), [duración de tokens en Testing](https://developers.google.com/identity/protocols/oauth2).

package/battle_reader.py

@@ -6,6 +6,12 @@ ROOT = pathlib.Path(__file__).resolve().parent
 def parse(xml):
     root = ET.fromstring(xml)
     nodes = [n for n in root.iter('node') if n.get('package') == 'com.goonhammer.ttba' and (n.get('content-desc') or n.get('text'))]
+    parents = {child: parent for parent in root.iter() for child in parent}
+    def enabled(node):
+        while node is not None:
+            if node.get('enabled') == 'false': return False
+            node = parents.get(node)
+        return True
     texts = [(n.get('content-desc') or n.get('text')).strip() for n in nodes]
     header = next((re.fullmatch(r'(\d+)\s*[-–]\s*(\d+)\s+(.+?) vs (.+)', t) for t in texts if re.fullmatch(r'(\d+)\s*[-–]\s*(\d+)\s+(.+?) vs (.+)', t)), None)
     rnd = next((int(m[1]) for t in texts if (m := re.fullmatch(r'Round (\d+)', t))), None)
@@ -36,21 +42,55 @@ def parse(xml):
             current[m[1].lower()] = {'score': int(m[2]), 'max': int(m[3])}
         if section == 'PRIMARY':
             details = re.fullmatch(r'(.+)\n(\d+VP.*)', t)
-            if not details and i+1 < len(texts) and re.match(r'\d+VP', texts[i+1]):
+            counter_index = None
+            # Flutter exposes split rows in either label/rule/value or rule/label/value order.
+            label = '\n' not in t and not t.isdigit() and not re.match(r'\d+VP|PRIMARY:', t)
+            if not details and label and i+2 < len(texts) and re.match(r'\d+VP', texts[i+1]) and texts[i+2].isdigit():
                 details = (None, t, texts[i+1])
+                counter_index = i+2
+            elif not details and label and i>0 and i+1<len(texts) and re.match(r'\d+VP',texts[i-1]) and texts[i+1].isdigit():
+                details = (None, t, texts[i-1])
+                counter_index = i+1
             if details:
                 if current['primaryObjectives'] is None: current['primaryObjectives'] = []
                 checkboxes = [n for n in nodes[i].iter('node') if n.get('checkable') == 'true']
                 checked = checkboxes[0].get('checked') == 'true' if len(checkboxes) == 1 else None
                 counter = None
-                # Split counter rows expose label, scoring rule, then numeric value.
-                if '\n' not in t and i+2 < len(texts) and texts[i+2].isdigit():
-                    counter = int(texts[i+2])
-                current['primaryObjectives'].append({'name': details[1], 'details': details[2], 'checked': checked, 'counter': counter})
+                if counter_index is not None:
+                    counter = int(texts[counter_index])
+                current['primaryObjectives'].append({'name': details[1], 'details': details[2], 'checked': checked, 'counter': counter, 'enabled': enabled(nodes[i])})
         m = re.fullmatch(r'(.+)\n(\d+)\n/(\d+)(?:\n\+(\d+)pts)?', t)
         if m:
             if current['secondaries'] is None: current['secondaries'] = []
-            current['secondaries'].append(dict(name=m[1], score=int(m[2]), max=int(m[3])))
+            current['secondaries'].append(dict(name=m[1], score=int(m[2]), max=int(m[3]), enabled=enabled(nodes[i])))
+    # Only compare card membership when the entire secondary section is visible.
+    # A following player heading bounds it; for the final player require blank
+    # space below the last row and above the fixed round-navigation button.
+    def bounds(node):
+        v = re.fullmatch(r'\[(\d+),(\d+)\]\[(\d+),(\d+)\]', node.get('bounds', ''))
+        return tuple(map(int, v.groups())) if v else None
+    for player in players:
+        player['secondariesComplete'] = False
+    owner = None
+    for i, text in enumerate(texts):
+        if text in names:
+            owner = names.index(text)
+        if owner is None or not re.fullmatch(r'SECONDARY:\s*\d+/\d+', text):
+            continue
+        end = next((j for j in range(i+1, len(texts)) if texts[j] in names or re.fullmatch(r'Round \d+', texts[j])), None)
+        if end is None:
+            continue
+        section = texts[i+1:end]
+        if 'Select missions' not in section or 'Discard missions' not in section:
+            continue
+        complete = texts[end] in names
+        if not complete and owner == 1 and end > i+1:
+            last, tab = bounds(nodes[end-1]), bounds(nodes[end])
+            complete = bool(last and tab and tab[1]-last[3] >= max(100, last[3]-last[1]))
+        if complete:
+            players[owner]['secondariesComplete'] = True
+            if players[owner]['secondaries'] is None:
+                players[owner]['secondaries'] = []
     return dict(round=rnd, half=None, players=players)
 
 def merge(previous, fresh):

package/cli.js

@@ -7,6 +7,7 @@ const version=require('./package.json').version;
 const help=`wargaming-overlay ${version} — overlay local para OBS
 
   wargaming-overlay start                  Inicia el overlay y lector
+  wargaming-overlay youtube-auth --client-secret RUTA  Autoriza YouTube una vez
   wargaming-overlay doctor                 Revisa Python, ADB y teléfono
   wargaming-overlay setup                  Guía de configuración
   wargaming-overlay setup --install-adb    Instala ADB con el gestor del sistema
@@ -25,14 +26,16 @@ Por defecto: ~/Library/Application Support/wargaming-overlay en macOS;
 %LOCALAPPDATA%/wargaming-overlay en Windows; ~/.local/share/wargaming-overlay en Linux. Solo escucha en 127.0.0.1.
 Ctrl+C detiene el servidor y lector. El último estado queda guardado.
 `;
-function main(){
+async function main(){
  const args=process.argv.slice(2);
  if(args.includes('--help')||args.includes('-h')){console.log(help);return}
  if(args.includes('--version')){console.log(version);return}
  const command=args.shift()||'start',options={};let source;
- const keys={'--port':'port','--serial':'serial','--interval':'interval','--adb':'adb','--python':'python','--data-dir':'dataDir'};
+ const keys={'--port':'port','--serial':'serial','--interval':'interval','--adb':'adb','--python':'python','--data-dir':'dataDir','--client-secret':'clientSecret'};
  while(args.length){const a=args.shift();if(a==='--install-adb')options.install=true;else if(a==='--dry-run')options.dryRun=true;else if(keys[a]){const value=args.shift();if(!value||value.startsWith('--'))throw Error(`Falta el valor de ${a}`);options[keys[a]]=value}else if(command==='migrate'&&!source&&!a.startsWith('-'))source=a;else throw Error(`Argumento desconocido: ${a}. Usa --help.`)}
- if(!['start','doctor','setup','migrate'].includes(command))throw Error('Comando desconocido. Usa --help.');
+ if(!['start','doctor','setup','migrate','youtube-auth'].includes(command))throw Error('Comando desconocido. Usa --help.');
+ if(options.clientSecret && command!=='youtube-auth')throw Error('--client-secret solo se usa con youtube-auth.');
+ if(command==='youtube-auth'){await new (require('./youtube/auth').Auth)().authorize(options.clientSecret);return;}
  const dataDir=path.resolve(options.dataDir||dataDirectory());
  if((options.install||options.dryRun)&&command!=='setup')throw Error('--install-adb y --dry-run solo se usan con setup.');
  if(command==='migrate'){
@@ -75,4 +78,4 @@ function main(){
  process.env.OVERLAY_DATA_DIR=dataDir;process.env.PORT=String(port);process.env.OVERLAY_ADB=r.adb;process.env.OVERLAY_PYTHON=r.python;process.env.OVERLAY_SERIAL=options.serial||'';process.env.OVERLAY_INTERVAL=String(interval);
  require('./server');
 }
-try{main()}catch(e){console.error('Error: '+e.message);process.exitCode=1}
+main().catch(e=>{console.error('Error: '+e.message);process.exitCode=1;});

package/device_connection.py

@@ -0,0 +1,122 @@
+"""Track one physical Android device across authorized ADB transports."""
+import json
+import os
+import re
+import subprocess
+import time
+from pathlib import Path
+
+
+def run_adb(*args):
+    return subprocess.run([os.environ.get('OVERLAY_ADB', 'adb'), *args],
+                          capture_output=True, text=True, encoding='utf-8',
+                          errors='replace', check=True, timeout=5).stdout
+
+
+def devices(output):
+    rows = []
+    for line in output.splitlines():
+        fields = line.split()
+        if len(fields) >= 2 and not line.startswith(('List of', '*')):
+            serial = fields[0]
+            wireless = ':' in serial or '._adb-tls-connect._tcp' in serial
+            rows.append({'serial': serial, 'state': fields[1],
+                         'transport': 'wifi' if wireless else 'usb'})
+    return rows
+
+
+class DeviceConnection:
+    def __init__(self, serial='', path=None, run=run_adb, now=time.monotonic):
+        self.run, self.now, self.explicit = run, now, serial
+        self.path = Path(path) if path else None
+        self.identity, self.aliases = None, set()
+        self.retry_at = 0
+        if self.path:
+            try:
+                saved = json.loads(self.path.read_text())
+                if not serial or serial in saved.get('aliases', []):
+                    self.identity = saved.get('identity')
+                    self.aliases = set(saved.get('aliases', []))
+            except (OSError, ValueError, TypeError):
+                pass
+
+    def identify(self, serial):
+        for prop in ('ro.serialno', 'ro.boot.serialno'):
+            try:
+                value = self.run('-s', serial, 'shell', 'getprop', prop).strip()
+                if value and value.lower() not in ('unknown', 'null'):
+                    return value
+            except (OSError, subprocess.SubprocessError):
+                pass
+        return None
+
+    def remember(self, matching):
+        self.aliases.update(d['serial'] for d in matching)
+        if self.path:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            temp = self.path.with_suffix('.tmp')
+            temp.write_text(json.dumps({'identity': self.identity, 'aliases': sorted(self.aliases)}))
+            temp.replace(self.path)
+
+    def reconnect(self, discover_only=False):
+        if not self.identity or self.now() < self.retry_at:
+            return
+        self.retry_at = self.now() + 15
+        known = {a for a in self.aliases if ':' in a and not a.startswith('adb-')}
+        discovered = set()
+        # Only discover services advertising the remembered device, never arbitrary LAN phones.
+        try:
+            for line in self.run('mdns', 'services').splitlines():
+                fields = line.split()
+                if (len(fields) >= 3 and fields[0].startswith('adb-' + self.identity + '-')
+                        and '_adb-tls-connect._tcp' in fields[1]):
+                    discovered.add(fields[2])
+        except (OSError, subprocess.SubprocessError):
+            pass
+        # Current advertisements take priority over obsolete ports stored in history.
+        targets = sorted(discovered) + ([] if discover_only else sorted(known - discovered))
+        for target in targets[:4]:
+            if re.fullmatch(r'[A-Za-z0-9.\-\[\]:]+:\d+', target):
+                try:
+                    result = self.run('connect', target)
+                    if 'connected to' in result and self.identify(target) == self.identity:
+                        self.remember([{'serial': target}])
+                        break
+                except (OSError, subprocess.SubprocessError):
+                    pass
+
+    def select(self):
+        rows = devices(self.run('devices', '-l'))
+        ready = [d for d in rows if d['state'] == 'device']
+        # Verify the physical identity even for remembered IP addresses: DHCP can reuse them.
+        for d in ready:
+            d['identity'] = self.identify(d['serial'])
+        if self.identity:
+            matching = [d for d in ready if d['identity'] == self.identity]
+        elif self.explicit:
+            matching = [d for d in ready if d['serial'] == self.explicit]
+            if matching:
+                self.identity = matching[0]['identity']
+                if self.identity:
+                    matching = [d for d in ready if d['identity'] == self.identity]
+        else:
+            identities = {d['identity'] or d['serial'] for d in ready}
+            if len(identities) > 1:
+                raise ValueError('Hay varios teléfonos diferentes. Selecciona uno con --serial SERIAL.')
+            matching = ready
+            if matching:
+                self.identity = matching[0]['identity']
+        if not matching:
+            self.reconnect()
+            if any(d['state'] == 'unauthorized' for d in rows):
+                raise ValueError('Autoriza este computador en el teléfono; para Wi-Fi completa el emparejamiento de depuración inalámbrica.')
+            raise ValueError('Reconectando al teléfono seleccionado por USB o Wi-Fi. Comprueba la conexión y la depuración inalámbrica.')
+        # If identity is unavailable, stick to the chosen transport, never guess another phone.
+        chosen = sorted(matching, key=lambda d: d['transport'] != 'usb')[0]
+        if not self.identity:
+            self.explicit = chosen['serial']
+        self.remember(matching)
+        # Establish Wi-Fi while USB is still available, without delaying on stale IPs.
+        if chosen['transport'] == 'usb' and not any(d['transport'] == 'wifi' for d in matching):
+            self.reconnect(discover_only=True)
+        return chosen

package/diagnostics.js

@@ -33,6 +33,12 @@ function check(options={}){
  if(py.status!==0)return {ok:false,code:'PYTHON_VERSION',message:'Se necesita Python 3.8 o posterior. Usa --python /ruta/a/python3.',adb,python};
  const result=spawnSync(adb,['devices','-l'],{encoding:'utf8',timeout:15000});
  if(result.error||result.status!==0)return {ok:false,code:'ADB_ERROR',message:'ADB no pudo consultar el teléfono: '+(result.error?.message||(result.stderr||'').trim()).slice(0,600),adb,python};
- return {...deviceStatus(result.stdout,options.serial),adb,python};
+ let status=deviceStatus(result.stdout,options.serial);
+ // USB and wireless transports can be the same physical phone.
+ if(status.code==='MULTIPLE_DEVICES'){
+  const probe=spawnSync(python,['-c', 'import json; from device_connection import DeviceConnection; print(json.dumps(DeviceConnection().select()))'],{cwd:__dirname,env:{...process.env,OVERLAY_ADB:adb},encoding:'utf8',timeout:20000,windowsHide:true});
+  if(probe.status===0){try{const d=JSON.parse(probe.stdout);status={ok:true,code:'READY',message:'Teléfono conectado por '+(d.transport==='wifi'?'Wi-Fi.':'USB.'),serial:d.serial};}catch{}}
+ }
+ return {...status,adb,python};
 }
 module.exports={locate,deviceStatus,check,findPython};

package/game-store.js

@@ -2,19 +2,41 @@ const {inferTurn}=require('./turn-tracker');
 const emptyGame=()=>({players:[],connected:false,updatedAt:null,error:null});
 function mergeGame(previous,incoming){
  if(!incoming.connected || !Array.isArray(incoming.players) || incoming.players.length!==2)
-  return {...previous,connected:false,error:incoming.error||'Sin lectura válida'};
- const same=previous.round===incoming.round && previous.players?.length===2 && incoming.players.every(p=>previous.players.some(old=>old.name===p.name));
+  return {...previous,connected:false,phoneConnected:incoming.phoneConnected===true,transport:incoming.transport||null,error:incoming.error||'Sin lectura válida'};
+ const samePlayers=previous.players?.length===2 && incoming.players.every(p=>previous.players.some(old=>old.name===p.name));
+ const same=samePlayers && previous.round===incoming.round;
+ const advance=samePlayers && incoming.round===previous.round+1 && incoming.round>(previous.turn?.highestRound??previous.round);
  const players=incoming.players.map(p=>{
-  const old=same?previous.players.find(old=>old.name===p.name):null;
+  const prior=samePlayers?previous.players.find(old=>old.name===p.name):null;
+  const old=same?prior:advance?{
+   // Primary/secondary totals are cumulative; objective progress belongs to the round.
+   cp:prior.cp,primary:prior.primary,secondary:prior.secondary,
+   secondaries:prior.secondaries?.filter(m=>m.score===0),
+   primaryObjectives:prior.primaryObjectives?.map(m=>({...m,checked:m.checked==null?null:false,counter:m.counter==null?null:0})),
+   observedAt:prior.observedAt
+  }:null;
   const merged={...p,observedAt:{}};
   for(const key of ['cp','primary','secondary','secondaries','primaryObjectives']){
    if(p[key]!=null)merged.observedAt[key]=incoming.updatedAt;
    else {merged[key]=old?.[key]??null;merged.observedAt[key]=old?.observedAt?.[key]??null;}
   }
+  // A partial viewport cannot establish that a remembered mission was removed.
+  for(const key of ['secondaries','primaryObjectives']){
+   if(Array.isArray(p[key]) && p[key].length && Array.isArray(old?.[key]) && !(key==='secondaries' && p.secondariesComplete)){
+    const identity=m=>key==='primaryObjectives'?JSON.stringify([m.name,m.details||'']):m.name;
+    const byName=new Map(old[key].map(m=>[identity(m),m]));
+    for(const m of p[key])byName.set(identity(m),m);
+    merged[key]=[...byName.values()];
+   }
+  }
   return merged;
  });
- const samePlayers=previous.players?.length===2 && incoming.players.every(p=>previous.players.some(old=>old.name===p.name));
  const turn=inferTurn(previous,incoming,samePlayers);
+ // Carried cards are known history, not newly drawn cards when first scrolled into view.
+ if(advance){
+  turn.cards=turn.cards||{};
+  for(const p of players)turn.cards[p.name]=[...new Set([...(turn.cards[p.name]||[]),...(p.secondaries||[]).map(m=>m.name)])];
+ }
  return {...incoming,players,turn,half:incoming.round===turn.highestRound?turn.half:null};
 }
 module.exports={emptyGame,mergeGame};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ing.jorgeu/wargaming-overlay",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Overlay local para OBS con lectura Android por ADB",
   "bin": {
     "wargaming-overlay": "cli.js"
@@ -9,7 +9,8 @@
     "start": "node cli.js start",
     "test": "node --test",
     "prepublishOnly": "npm test",
-    "facts:coverage": "node scripts/fact-coverage.js"
+    "facts:coverage": "node scripts/fact-coverage.js",
+    "test-tts": "node scripts/tts-demo.js"
   },
   "engines": {
     "node": ">=20"
@@ -21,6 +22,7 @@
     "reader.py",
     "battle_reader.py",
     "game-store.js",
+    "reader-status.js",
     "turn-tracker.js",
     "public",
     "README.md",
@@ -32,7 +34,11 @@
     "announcements.js",
     "data/faction-facts.json",
     "factions.js",
-    "scripts/fact-coverage.js"
+    "scripts/fact-coverage.js",
+    "device_connection.py",
+    "youtube",
+    "tts",
+    "scripts/tts-demo.js"
   ],
   "license": "0BSD",
   "publishConfig": {
@@ -49,5 +55,9 @@
     "wargaming",
     "adb",
     "cli"
-  ]
+  ],
+  "dependencies": {
+    "@grpc/grpc-js": "^1.14.5",
+    "@grpc/proto-loader": "^0.8.1"
+  }
 }

package/public/control.html

@@ -1,6 +1,6 @@
 <!doctype html><html lang="es"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Battle Report Control</title><link rel="stylesheet" href="style.css"></head><body class="control">
 <main><header><p class="eyebrow">BATTLE REPORT</p><h1>Control de transmisión</h1><p>Los cambios se reflejan al instante en OBS.</p></header>
-<form id="form"><label>Rótulo del encuentro<input id="title" maxlength="40"></label><section id="players"></section><p>Top / Bottom se detecta automáticamente a partir de la puntuación registrada en Tabletop Battles.</p><div class="announcement-actions"><button type="submit" disabled>Actualizar overlay</button><button type="button" id="swap-players" class="secondary-button" disabled>Intercambiar jugadores ⇄</button></div><p>Intercambiar jugadores guarda los cambios del formulario y mueve nombres, facciones, destacamentos y marcadores al lado contrario.</p><p id="saved" aria-live="polite"></p></form><section><h2>Datos de la partida</h2><p id="phone-status" aria-live="polite"></p><p id="turn-status" aria-live="polite"></p><button type="button" id="reset-game">Restablecer datos de la partida</button><p>Vacía los puntos y misiones guardados. Conserva nombres, facciones y diseño. Si el teléfono está conectado, la próxima lectura los volverá a completar.</p><p id="reset-status" aria-live="polite"></p></section><section class="announcement-panel" aria-labelledby="announcement-heading">
+<form id="form"><label>Rótulo del encuentro<input id="title" maxlength="40"></label><section id="players"></section><p>Top / Bottom se detecta automáticamente a partir de la puntuación registrada en Tabletop Battles.</p><div class="announcement-actions"><button type="submit" disabled>Actualizar overlay</button><button type="button" id="swap-players" class="secondary-button" disabled>Intercambiar jugadores ⇄</button></div><p>Intercambiar jugadores guarda los cambios del formulario y mueve nombres, facciones, destacamentos y marcadores al lado contrario.</p><p id="saved" aria-live="polite"></p></form><section><h2>Datos de la partida</h2><p id="phone-status" aria-live="polite"></p><div class="turn-indicator" aria-live="polite"><strong id="turn-status">RONDA —</strong><p id="turn-order">Esperando la lectura de Tabletop Battles.</p><p id="turn-reason"></p></div><button type="button" id="reset-game">Restablecer datos de la partida</button><p>Vacía los puntos y misiones guardados. Conserva nombres, facciones y diseño. Si el teléfono está conectado, la próxima lectura los volverá a completar.</p><p id="reset-status" aria-live="polite"></p></section><section class="announcement-panel" aria-labelledby="announcement-heading">
 <h2 id="announcement-heading">Mensajes en pantalla</h2>
 <p>Se muestran abajo durante 15 segundos. Primero guarda las facciones y disposiciones del encuentro.</p>
 <form id="message-form"><label for="toast-message">Mensaje para la transmisión</label><textarea id="toast-message" rows="3" maxlength="280" placeholder="¡Bienvenidos! La próxima ronda comienza en unos minutos." required></textarea><div class="announcement-actions"><span id="message-count">0 / 280</span><button type="submit">Mostrar mensaje · 15 s</button></div></form>
@@ -8,5 +8,5 @@
 <div class="announcement-actions"><button type="button" id="next-fact">Mostrar siguiente dato</button><button type="button" class="secondary-button" id="new-toast-session">Nueva sesión de mensajes</button></div>
 <p id="rotation-status" aria-live="polite"></p><p id="toast-feedback" role="status"></p>
 <div class="announcement-preview"><span class="eyebrow">ÚLTIMO MENSAJE</span><p id="last-toast">Todavía no has mostrado un mensaje.</p><a id="toast-source" target="_blank" rel="noopener noreferrer" hidden>Consultar fuente</a></div>
-<p class="announcement-help">El orden es aleatorio y cada dato aparece una sola vez por sesión. Al agotarse, la rotación espera sin repetir. El historial se conserva al recargar o reiniciar. «Nueva sesión» lo reinicia para otra transmisión. Los mensajes manuales reemplazan el aviso actual.</p>
+<p class="announcement-help">El orden es aleatorio y cada dato aparece una sola vez por ciclo. Al agotarse, comienza otro ciclo automáticamente. El historial se conserva al recargar o reiniciar. «Nueva sesión» lo reinicia para otra transmisión. Los mensajes manuales reemplazan el aviso actual.</p>
 </section><aside><strong>En OBS:</strong> añade una fuente “Navegador” con la URL <code id="obs-url"></code>. Resolución de la fuente: <select id="resolution-preset"><option value="1280x720">720p · 1280 × 720</option><option value="1600x900">900p · 1600 × 900</option><option value="1664x936">936p · 1664 × 936</option><option value="1920x1080">1080p · 1920 × 1080</option><option value="2560x1440" selected>1440p · 2560 × 1440</option><option value="3840x2160">4K · 3840 × 2160</option></select><p id="resolution-help"></p></aside></main><script src="match-view.js"></script><script src="control.js"></script><script src="announcements-control.js"></script></body></html>

package/public/control.js

@@ -47,7 +47,7 @@ document.querySelector('#reset-game').addEventListener('click',async()=>{
  catch {document.querySelector('#reset-status').textContent='No se pudo restablecer. Comprueba que el servidor esté actualizado y funcionando.';}
  finally{button.disabled=false}
 });
-async function phoneStatus(){try{const r=await fetch('/game-state.json',{cache:'no-store'});const g=await r.json();document.querySelector('#turn-status').textContent=(g.half==='top'?'TOP · Primer turno. ':g.half==='bottom'?'BOTTOM · Segundo turno. ':'Turno automático: ')+(g.turn?.reason||'Esperando actividad de puntuación.');document.querySelector('#phone-status').textContent=g.connected?'Teléfono conectado.':(g.error||'Sin conexión.')+(g.players?.length?' Se conserva la última lectura.':'');}catch{document.querySelector('#phone-status').textContent='Servidor no disponible.'}finally{setTimeout(phoneStatus,3000)}}phoneStatus();
+async function phoneStatus(){try{const r=await fetch('/game-state.json',{cache:'no-store'});const g=await r.json();const turn=MatchView.turnStatus(g,state);document.querySelector('#turn-status').textContent=turn.label;document.querySelector('#turn-order').textContent=turn.order;document.querySelector('#turn-reason').textContent=turn.reason;document.querySelector('#phone-status').textContent=g.connected?`Teléfono conectado por ${g.transport==='wifi'?'Wi-Fi':'USB'}.`:(g.phoneConnected?`Teléfono conectado por ${g.transport==='wifi'?'Wi-Fi':'USB'}. `:'')+(g.error||'Reconectando…')+(g.players?.length?' Se conserva la última lectura.':'');}catch{document.querySelector('#phone-status').textContent='Servidor no disponible.'}finally{setTimeout(phoneStatus,3000)}}phoneStatus();
 
 document.querySelector('#obs-url').textContent=location.origin+'/overlay-art.html';
 

package/public/live-score.css

@@ -1,7 +1,7 @@
-.live-score{color:#fffaf0;text-shadow:0 2px 4px #000,0 0 8px #000;pointer-events:none}.live-vp{position:absolute;transform:translateY(-50%);font-size:40px;white-space:nowrap;font-variant-numeric:tabular-nums}.live-cp{position:absolute;transform:translateX(-50%);font-size:34px;white-space:nowrap}.live-round{position:absolute;top:145px;left:50%;transform:translateX(-50%);font-size:28px;white-space:nowrap}.live-missions{position:absolute;top:248px;width:350px;font-size:28px;line-height:1.55;text-transform:none}.live-player.left .live-missions{left:24px}.live-player.right .live-missions{right:24px;text-align:right}.live-mission{overflow-wrap:anywhere}.live-note{display:none}
+.live-score{color:#fffaf0;text-shadow:0 2px 4px #000,0 0 8px #000;pointer-events:none}.live-vp{position:absolute;transform:translateY(-50%);font-size:40px;white-space:nowrap;font-variant-numeric:tabular-nums}.live-cp{position:absolute;transform:translateX(-50%);font-size:34px;white-space:nowrap}.live-round{position:absolute;top:145px;left:50%;transform:translateX(-50%);font-size:28px;white-space:nowrap}.live-missions{position:absolute;top:248px;width:350px;font-size:30px;line-height:1.35;text-transform:none}.live-player.left .live-missions{left:24px}.live-player.right .live-missions{right:24px;text-align:right}.live-mission{overflow-wrap:anywhere}.live-note{display:none}
 
-.live-primary{padding-bottom:12px;margin-bottom:12px;border-bottom:1px solid rgba(255,250,240,.5)}.mission-heading{font-size:18px;letter-spacing:.12em;margin-bottom:6px;color:#e2ceb0}.primary-objective{font-size:22px;line-height:1.3;margin:7px 0}.live-missions{width:400px}
+.live-primary{padding-bottom:12px;margin-bottom:12px;border-bottom:1px solid rgba(255,250,240,.5)}.mission-heading{font-size:18px;letter-spacing:.12em;margin-bottom:6px;color:#e2ceb0}.primary-objective{font-size:28px;line-height:1.25;margin:12px 0}.live-missions{width:400px}
 
-.primary-objective{display:flex;align-items:flex-start;justify-content:space-between;gap:12px}.objective-name{flex:1}.objective-check,.objective-counter{flex:0 0 auto;min-width:27px;height:27px;display:inline-flex;align-items:center;justify-content:center;font-size:23px;line-height:1;font-variant-numeric:tabular-nums}.objective-check{border:2px solid #fffaf0aa;border-radius:4px}.objective-check.completed{color:#bcf2c2;border-color:#bcf2c2}.objective-counter{font-weight:bold}
+.primary-objective{display:flex;align-items:flex-start;justify-content:space-between;gap:12px}.objective-copy{flex:1;min-width:0}.objective-name{overflow-wrap:anywhere}.objective-details{font-size:20px;line-height:1.3;color:#e2ceb0;margin-top:4px;overflow-wrap:anywhere}.objective-check,.objective-counter{flex:0 0 auto;min-width:30px;height:30px;display:inline-flex;align-items:center;justify-content:center;font-size:26px;line-height:1;font-variant-numeric:tabular-nums}.objective-check{border:2px solid #fffaf0aa;border-radius:4px}.objective-check.completed{color:#bcf2c2;border-color:#bcf2c2}.objective-counter{font-weight:bold}
 
 .live-round{z-index:6;padding:7px 16px;background:rgba(7,10,14,.96);border:1px solid rgba(232,228,216,.65);border-radius:7px;box-shadow:0 3px 10px #0008;line-height:1.15}

package/public/live-score.js

@@ -15,9 +15,12 @@
    if(p?.primary){
     const primary=make('section','','live-primary');
     primary.append(make('div',`PRIMARIA · ${value(p.primary)}`,'mission-heading'));
-    for(const objective of p.primaryObjectives||[]){
+    for(const objective of (p.primaryObjectives||[]).filter(m=>m.enabled!==false)){
      const row=make('div','','primary-objective');
-     row.append(make('span',objective.name,'objective-name'));
+     const copy=make('div','','objective-copy');
+     copy.append(make('div',objective.name,'objective-name'));
+     if(objective.details)copy.append(make('div',objective.details,'objective-details'));
+     row.append(copy);
      const hasCounter=objective.counter!=null;
      const marker=make('span',hasCounter?String(objective.counter):objective.checked===true?'✓':objective.checked===false?'':'—',hasCounter?'objective-counter':'objective-check');
      marker.setAttribute('aria-label',hasCounter?`Contador: ${objective.counter}`:objective.checked===true?'Cumplida':objective.checked===false?'Pendiente':'Sin lectura');
@@ -26,8 +29,9 @@
     }
     missions.append(primary);
    }
-   if(p?.secondaries?.length)missions.append(make('div','SECUNDARIAS','mission-heading'));
-   for(const m of p?.secondaries||[])missions.append(make('div',`${m.name}  ${m.score}/${m.max}`,'live-mission'));
+   const secondaries=(p?.secondaries||[]).filter(m=>m.enabled!==false);
+   if(secondaries.length)missions.append(make('div','SECUNDARIAS','mission-heading'));
+   for(const m of secondaries)missions.append(make('div',`${m.name}  ${m.score}/${m.max}`,'live-mission'));
    if(!p)card.append(make('div','Sin jugador vinculado','live-note'));
    panel.append(card);
    const rect=document.querySelector('.team.'+side+' .faction-icon').getBoundingClientRect();

package/public/match-view.js

@@ -7,7 +7,7 @@
   }
   function matchPlayers(layout, game) {
     const matches = ['left', 'right'].map(side => {
-      const key = normalize(layout[side].appName || layout[side].name);
+      const key = normalize(layout?.[side]?.appName || layout?.[side]?.name);
       if (!key) return null;
       const found = (game?.players || []).filter(player => normalize(player.name) === key);
       return found.length === 1 ? found[0] : null;
@@ -17,10 +17,21 @@
   }
   function roundLabel(layout, game, matched) {
     const round = matched && Number.isInteger(game?.round) && game.round > 0 ? game.round : '—';
-    const half = {top: 'TOP · PRIMER TURNO', bottom: 'BOTTOM · SEGUNDO TURNO'}[matched ? game?.half : null];
-    return `RONDA ${round}${half ? ` · ${half}` : ''}`;
+    const half = {top: 'TOP', bottom: 'BOTTOM'}[matched ? game?.half : null];
+    const first=game?.turn?.firstPlayer;
+    const active=half && first ? game?.players?.find(p=>game.half==='top' ? p.name===first : p.name!==first) : null;
+    const matches=matchPlayers(layout,game);
+    const side=active ? matches.indexOf(active) : -1;
+    const color=side===0?'AZUL':side===1?'ROJO':null;
+    return `RONDA ${round}${half ? ` · ${half}` : ''}${color ? ` · ${color}` : ''}`;
   }
-  const api = {swapPlayers, matchPlayers, roundLabel};
+  function turnStatus(game, layout={}) {
+    const label=roundLabel(layout,game,Number.isInteger(game?.round));
+    const first=game?.turn?.orderSource==='ui-order' ? game.turn.firstPlayer : null;
+    const second=first ? game.players?.find(p=>p.name!==first)?.name : null;
+    return {label,order:first && second ? `TOP: ${first} · BOTTOM: ${second}` : 'Orden de jugadores pendiente de lectura',reason:game?.turn?.reason || 'Esperando nuevas secundarias en Tabletop Battles.'};
+  }
+  const api = {swapPlayers, matchPlayers, roundLabel, turnStatus};
   if (typeof module !== 'undefined' && module.exports) module.exports = api;
   else root.MatchView = api;
 })(globalThis);

package/public/style.css

@@ -8,3 +8,5 @@
 .control .secondary-button{background:transparent;border:1px solid #647284;color:#e8e4d8}.control button:disabled{opacity:.5;cursor:wait}
 .announcement-preview{background:#101620;border-left:3px solid #d9ad4a;padding:14px 18px;border-radius:3px}.announcement-preview p{white-space:pre-wrap;overflow-wrap:anywhere}.announcement-preview a{color:#e8bf70;font-size:13px}
 .announcement-help{font-size:13px;color:#b9c1cd}#toast-feedback{color:#e8bf70;min-height:24px}
+
+.turn-indicator{margin:16px 0;padding:18px;border:2px solid #c59b52;border-radius:12px;background:#172335;color:#fff}.turn-indicator strong{display:block;font-size:1.35rem}.turn-indicator p{margin:8px 0 0}#turn-reason{font-size:.9rem;opacity:.8}

package/reader-status.js

@@ -0,0 +1,19 @@
+// Log state transitions, never every polling cycle or score update.
+function createReaderStatus(log=console.log){
+ let last=null;
+ return incoming=>{
+  const transport=incoming.transport==='wifi'?'Wi-Fi':incoming.transport==='usb'?'USB':'conexión desconocida';
+  let key,message;
+  if(incoming.connected){
+   const names=(incoming.players||[]).map(p=>p.name).join(' vs ');
+   key=JSON.stringify(['reading',transport,names,incoming.round]);
+   message=`Leyendo teléfono por ${transport}: ${names} · ronda ${incoming.round}. Actualización automática activa.`;
+  }else{
+   const phone=incoming.phoneConnected?`Teléfono conectado por ${transport}; lectura pendiente`:'Sin lectura del teléfono';
+   key=JSON.stringify(['waiting',incoming.phoneConnected,transport,incoming.error]);
+   message=`${phone}: ${incoming.error||'buscando conexión USB o Wi-Fi; se reintentará automáticamente.'}`;
+  }
+  if(key!==last){log(message);last=key;}
+ };
+}
+module.exports={createReaderStatus};

package/reader.py

@@ -5,32 +5,23 @@ from battle_reader import parse, capture
 ADB = os.environ.get('OVERLAY_ADB', 'adb')
 SERIAL = os.environ.get('OVERLAY_SERIAL', '')
 
-def select_device(output):
-    devices = [line.split()[:2] for line in output.splitlines() if line.strip() and not line.startswith(('List of', '*'))]
-    if not devices:
-        raise ValueError('ADB no detecta un teléfono. Conecta un cable de datos, desbloquea Android y activa Opciones de desarrollador → Depuración USB. No se puede distinguir cable desconectado de depuración desactivada.')
-    if not SERIAL and len(devices) > 1:
-        raise ValueError('Hay varios dispositivos. Reinicia con --serial SERIAL: ' + ', '.join(d[0] for d in devices))
-    device = next((d for d in devices if d[0] == SERIAL), None) if SERIAL else devices[0]
-    if not device: raise ValueError('El dispositivo seleccionado no está conectado: ' + SERIAL)
-    serial, status = device
-    if status == 'unauthorized': raise ValueError('Teléfono sin autorizar. Desbloquéalo y acepta «Permitir depuración USB» para este equipo. Si no aparece, reconecta el cable.')
-    if status == 'no': raise ValueError('Sin permisos USB. Revisa reglas udev y grupos del usuario; en Ubuntu, android-sdk-platform-tools-common y plugdev. Vuelve a iniciar sesión después de cambiar grupos.')
-    if status == 'offline': raise ValueError('Teléfono offline. Desbloquéalo y reconecta el cable USB.')
-    if status != 'device': raise ValueError('Dispositivo no disponible: ' + status)
-    return serial
+from device_connection import DeviceConnection
+from pathlib import Path
 
 if __name__ == '__main__':
+    data_dir = os.environ.get('OVERLAY_DATA_DIR')
+    connection = DeviceConnection(SERIAL, Path(data_dir) / 'phone-connection.json' if data_dir else None)
     while True:
+        device = None
         try:
-            result = subprocess.run([ADB, 'devices', '-l'], capture_output=True, text=True, encoding='utf-8', errors='replace', check=True, timeout=10)
-            serial = select_device(result.stdout)
+            device = connection.select()
+            serial = device['serial']
             state = parse(capture(serial))
-            print(json.dumps(dict(state, connected=True, updatedAt=time.time(), error=None)), flush=True)
+            print(json.dumps(dict(state, connected=True, phoneConnected=True, transport=device["transport"], deviceSerial=serial, updatedAt=time.time(), error=None)), flush=True)
         except Exception as e:
             message = str(e)
             if isinstance(e, subprocess.TimeoutExpired): message = 'El teléfono no respondió a tiempo. Desbloquéalo y abre la ronda; volveré a intentar la lectura.'
             elif isinstance(e, subprocess.CalledProcessError): message = 'No se pudo leer Android. Abre la ronda y cierra otros lectores UIAutomator. Se reintentará. ' + (e.stderr or '').strip()[:300]
             elif isinstance(e, FileNotFoundError): message = 'ADB no está disponible. Ejecuta wargaming-overlay setup --install-adb.'
-            print(json.dumps({'connected':False, 'error':message}), flush=True)
+            print(json.dumps({'connected':False, 'phoneConnected':device is not None and isinstance(e, ValueError), 'transport':device['transport'] if device is not None else None, 'error':message}), flush=True)
         time.sleep(float(os.environ.get('OVERLAY_INTERVAL', '3')))

package/scripts/tts-demo.js

@@ -0,0 +1,11 @@
+const {SpeechQueue}=require('../tts/queue');
+const {sanitize}=require('../tts/sanitizer');
+async function main(){
+ if(process.platform!=='darwin')throw Error('Esta prueba de voz requiere macOS.');
+ const q=new SpeechQueue();
+ for(const [author,text] of [['Pedro','Hola, esto es una prueba.'],['John','Este mensaje debe sonar después del anterior.'],['Pedro','Mira esto https://example.com/prueba']])q.enqueue(sanitize({author,text}));
+ const stop=()=>{q.stop();};process.once('SIGINT',stop);process.once('SIGTERM',stop);
+ await q.idle();process.removeListener('SIGINT',stop);process.removeListener('SIGTERM',stop);
+ if(q.failed)throw Error('La prueba de voz falló. Revisa los mensajes de TTS.');
+}
+main().catch(e=>{console.error(e.message);process.exitCode=1;});

package/server.js

@@ -14,17 +14,31 @@ function persistGame() { fs.writeFileSync(gamePath + '.tmp', JSON.stringify(game
 const readerOptions = { env: { ...process.env, PYTHONIOENCODING: "utf-8" }, stdio: ['ignore', 'pipe', 'inherit'] };
 if (process.env.SUDO_UID) { readerOptions.uid = Number(process.env.SUDO_UID); readerOptions.gid = Number(process.env.SUDO_GID); }
 let reader;
+let youtube;
 function startReader(){
-let lastError = '';
+const report = require('./reader-status').createReaderStatus();
+console.log('Buscando teléfono por USB o Wi-Fi… Esperando la primera lectura de Tabletop Battles.');
+let lastResponse=Date.now();
+let stalled=false;
+const watchdog=setInterval(()=>{
+ if(!stalled && Date.now()-lastResponse>30000){
+  stalled=true;console.error('El lector lleva más de 30 segundos sin responder. Comprueba el teléfono y la conexión; sigo esperando.');
+ }
+},5000);
+watchdog.unref();
 reader = spawn(process.env.OVERLAY_PYTHON || 'python3', [path.join(__dirname, 'reader.py')], readerOptions);
 readline.createInterface({ input: reader.stdout }).on('line', line => {
-  try { const incoming = JSON.parse(line); game = mergeGame(game, incoming); persistGame(); if (incoming.error !== lastError) { if (incoming.error) console.error(incoming.error); else if(lastError) console.log('Teléfono conectado. Lectura recuperada.'); lastError = incoming.error; } } catch (e) { console.error('Lectura:', e.message); }
+  try {
+   const incoming=JSON.parse(line);lastResponse=Date.now();
+   if(stalled){console.log('El lector volvió a responder.');stalled=false;}
+   game=mergeGame(game,incoming);persistGame();report(incoming);
+  } catch(e){console.error('Error procesando la lectura:',e.message);}
 });
-reader.on('error', e => console.error('Lector:', e.message));
-reader.on('exit', () => { game = mergeGame(game, {connected:false, error:'Lector detenido. Reinicia el servidor.'}); persistGame(); });
+reader.on('error', e => {clearInterval(watchdog);console.error('No se pudo iniciar el lector:',e.message);});
+reader.on('exit', (code,signal) => { clearInterval(watchdog);console.error(`Lector detenido (${signal||'código '+code}). Reinicia el servidor.`); game = mergeGame(game, {connected:false, error:'Lector detenido. Reinicia el servidor.'}); persistGame(); });
 }
-for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => { reader?.kill(); process.exit(); });
-process.on('exit', () => reader?.kill());
+for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => { reader?.kill(); youtube?.stop(); process.exit(); });
+process.on('exit', () => {reader?.kill();youtube?.queue?.clear();});
 const {syncStats} = require('./listhammer');
 const root = path.join(__dirname, 'public');
 const statePath = path.join(dataDir, 'overlay-state.json');
@@ -109,4 +123,4 @@ const server = http.createServer(async (req, res) => {
   send(res, 200, types[path.extname(filePath)] || 'application/octet-stream', fs.readFileSync(filePath));
 });
 server.on('error', e => { console.error(e.code==='EADDRINUSE' ? 'El puerto está ocupado. Detén el otro servidor o usa --port 8766.' : 'No se pudo iniciar: '+e.message); reader?.kill(); process.exitCode=1; });
-server.listen(Number(process.env.PORT || 8765), '127.0.0.1', () => { startReader(); syncStats(dataDir).then(stats => { statsCache = stats; announcements.refresh(); }).catch(e => console.error('Listhammer: ' + e.message + ' Se conserva la última copia completa, si existe. El overlay sigue funcionando; se reintentará en el próximo inicio.')); console.log(`Panel: http://127.0.0.1:${process.env.PORT || 8765}\nOBS: http://127.0.0.1:${process.env.PORT || 8765}/overlay-art.html\nDatos: ${dataDir}\nCtrl+C para detener.`); });
+server.listen(Number(process.env.PORT || 8765), '127.0.0.1', () => { startReader(); youtube=require('./youtube').startYouTube(dataDir); syncStats(dataDir).then(stats => { statsCache = stats; announcements.refresh(); }).catch(e => console.error('Listhammer: ' + e.message + ' Se conserva la última copia completa, si existe. El overlay sigue funcionando; se reintentará en el próximo inicio.')); console.log(`Panel: http://127.0.0.1:${process.env.PORT || 8765}\nOBS: http://127.0.0.1:${process.env.PORT || 8765}/overlay-art.html\nDatos: ${dataDir}\nCtrl+C para detener.`); });

package/tts/queue.js

@@ -0,0 +1,22 @@
+const {speak}=require('./speech');
+class SpeechQueue {
+ constructor({maxQueueLength=10,speech=speak,log=console.log}={}){this.max=maxQueueLength;this.speech=speech;this.log=log;this.queue=[];this.state='IDLE';this.closed=false;this.task=null;this.failed=0;}
+ enqueue(message){
+  if(this.closed)return;
+  if(this.queue.length>=this.max){this.queue.shift();this.log('[TTS] Se descartó el mensaje pendiente más antiguo: cola llena.');}
+  this.queue.push(message);this.log(`[TTS] En cola: ${message.author}. Pendientes: ${this.queue.length}.`);
+  if(!this.task)this.task=this.drain().finally(()=>{this.task=null;});
+ }
+ async drain(){
+  while(!this.closed&&this.queue.length){
+   const item=this.queue.shift();this.state='SPEAKING';this.controller=new AbortController();
+   this.log(`[TTS] Leyendo mensaje de ${item.author}.`);
+   try{await this.speech(item.spoken,{signal:this.controller.signal});}catch{this.failed++;this.log('[TTS] Falló la reproducción; continúo con el siguiente mensaje.');}
+  }
+  this.state='IDLE';
+ }
+ clear(){this.queue=[];this.controller?.abort();}
+ async stop(){this.closed=true;this.clear();await this.task;}
+ async idle(){await this.task;}
+}
+module.exports={SpeechQueue};

package/tts/sanitizer.js

@@ -0,0 +1,31 @@
+// Deliberately small local ES/EN filter, not semantic moderation.
+// Ordinary profanity and in-game violence are not blanket-blocked.
+const severe=[
+ /\b(?:n[i1]gg(?:er|a)s?|f[a4]gg?[o0]ts?|k[i1]kes?|sp[i1]cs?|sudacas?|maricones)\b/giu,
+ /\b(?:heil\s+hitler|sieg\s+heil)\b/giu,
+ /\b(?:te\s+voy\s+a\s+(?:matar|violar)|voy\s+a\s+(?:matarte|violarte)|i(?:'ll|\s+will)\s+(?:kill|rape)\s+you)\b/giu,
+ /\b(?:maten|matad|exterminen|hay\s+que\s+matar|kill|exterminate)\s+(?:(?:a|a\s+los|los|las|all|the)\s+)*(?:judios|negros|gays|musulmanes|inmigrantes|jews|blacks|muslims|immigrants)\b/giu,
+ /\b(?:chupa(?:me)?\s+(?:la\s+)?(?:polla|verga)|suck\s+my\s+(?:dick|cock)|(?:sexo|pornografia|porn)\s+(?:con\s+)?(?:ninos|menores|children))\b/giu
+];
+function truncate(text,max){const chars=Array.from(text);if(chars.length<=max)return text;let cut=chars.slice(0,max-1).join('');const space=cut.lastIndexOf(' ');if(space>max*.7)cut=cut.slice(0,space);return cut.trimEnd()+'…';}
+function clean(input,{filterUrls=true,extraBlockedTerms=[]}={}){
+ let text=String(input||'').slice(0,10000).normalize('NFKC').replace(/[\p{Cc}\p{Cf}]/gu,' ').replace(/[\[\]<>]/g,' ').replace(/\s+/g,' ').trim();
+ if(filterUrls)text=text.replace(/(?:[a-z][a-z\d+.-]*:\/\/|www\.)[^\s]+|\b(?:[\p{L}\d-]+\.)+[a-z]{2,63}(?:\/[^\s]*)?/giu,' Enlace ');
+ // Accent-insensitive matching with offsets mapped back to the original spelling.
+ const chars=Array.from(text),folded=[],offsets=[];let offset=0;
+ for(const ch of chars){const f=ch.normalize('NFD').replace(/\p{M}/gu,'');for(let j=0;j<f.length;j++)offsets.push([offset,offset+ch.length]);folded.push(f);offset+=ch.length;}
+ const normalized=folded.join(''),spans=[];
+ const patterns=[...severe,...extraBlockedTerms.filter(t=>typeof t==='string'&&t.trim()).slice(0,100).map(t=>new RegExp(t.normalize('NFD').replace(/\p{M}/gu,'').replace(/[.*+?^${}()|[\]\\]/g,'\\$&'),'giu'))];
+ for(const re of patterns){re.lastIndex=0;for(const m of normalized.matchAll(re))if(m[0].length)spans.push([offsets[m.index][0],offsets[m.index+m[0].length-1][1]]);}
+ spans.sort((a,b)=>a[0]-b[0]);const merged=[];
+ for(const span of spans){const last=merged.at(-1);if(last&&span[0]<=last[1])last[1]=Math.max(last[1],span[1]);else merged.push([...span]);}
+ for(const [start,end] of merged.reverse())text=text.slice(0,start)+'[censurado]'+text.slice(end);
+ return text.replace(/\s+/g,' ').trim();
+}
+function sanitize(message,config={}){
+ const text=truncate(clean(message.text,config),config.maxMessageLength||300);
+ if(!text || !text.replace(/\[censurado\]|[^\p{L}\p{N}]/gu,''))return null;
+ const author=truncate(clean(message.author,config),40)||'Usuario';
+ return {author,text,spoken:config.readUsername===false?text:`${author} dice: ${text}`};
+}
+module.exports={sanitize,clean,truncate};

package/tts/speech.js

@@ -0,0 +1,20 @@
+const {spawn}=require('node:child_process');
+function speak(text,{spawnImpl=spawn,platform=process.platform,signal,timeoutMs=120000}={}){
+ if(platform!=='darwin')return Promise.reject(Error('El TTS local requiere macOS.'));
+ if(signal?.aborted)return Promise.resolve();
+ return new Promise((resolve,reject)=>{
+  // Feed text through stdin, not a shell/option. Remove Apple's embedded speech commands.
+  const child=spawnImpl('/usr/bin/say',[],{stdio:['pipe','ignore','pipe'],shell:false});
+  let timedOut=false,done=false;
+  const stop=()=>child.kill('SIGKILL');
+  const timer=setTimeout(()=>{timedOut=true;stop();},timeoutMs);
+  const finish=(error)=>{if(done)return;done=true;clearTimeout(timer);signal?.removeEventListener('abort',stop);error?reject(error):resolve();};
+  signal?.addEventListener('abort',stop,{once:true});
+  child.stderr?.resume();child.stdin.on('error',()=>{});
+  child.once('error',()=>finish(Error('No se pudo iniciar la voz nativa de macOS.')));
+  child.once('close',code=>finish(signal?.aborted?null:timedOut?Error('Se agotó el tiempo de voz.'):code===0?null:Error('La voz de macOS terminó con un error.')));
+  child.stdin.end(String(text).replace(/[\[\]]/g,''));
+  if(signal?.aborted)stop();
+ });
+}
+module.exports={speak};

package/turn-tracker.js

@@ -1,35 +1,47 @@
-// Accessibility snapshots can be partial. Only increases of previously seen
-// values are activity; discovering a mission while scrolling is not activity.
+// Keep the union of observed cards for each player and round across partial snapshots.
+// A first-seen unscored card after the initial reading is a draw heuristic, not proof.
 function inferTurn(previous, incoming, samePlayers) {
- const fresh={firstPlayer:null,activePlayer:null,half:null,highestRound:incoming.round,eligible:incoming.round===1 && incoming.players.every(p=>p.score===0),seen:{},reason:'Esperando actividad para detectar el turno'};
+ // The parser keeps Tabletop Battles player order even when a heading is off-screen.
+ const firstPlayer=incoming.players[0].name;
+ const fresh={firstPlayer,orderSource:'ui-order',detectionSource:'secondary-draws',activePlayer:null,half:null,highestRound:incoming.round,seen:{},reason:'Orden de Tabletop Battles identificado; esperando nuevas secundarias para detectar el turno'};
  let t=samePlayers && previous.turn ? structuredClone(previous.turn) : fresh;
  if(incoming.round<t.highestRound) return {...t,reason:'Ronda histórica: turno sin determinar'};
- if(incoming.round>t.highestRound){t={...t,highestRound:incoming.round,eligible:true,seen:{},activePlayer:null,half:null};}
+ // Old versions learned order from scoring; discard that inference on migration.
+ if(t.orderSource!=='ui-order' || t.firstPlayer!==firstPlayer)t=fresh;
+ if(incoming.round>t.highestRound){t={...t,highestRound:incoming.round,seen:{},cards:{},cardBaselines:{},activePlayer:null,half:null,reason:fresh.reason};}
+ // Preserve card history, but discard halves inferred by the former scoring policy.
+ if(t.detectionSource!=='secondary-draws'){
+  t.detectionSource='secondary-draws';t.activePlayer=null;t.half=null;t.reason=fresh.reason;
+ }
  const events=[];
+ t.cards=t.cards||{};
  for(const p of incoming.players){
-  const old=t.seen[p.name]||{},next={...old};let activity=false;
-  const values={};
-  for(const key of ['primary','secondary']) if(Number.isFinite(p[key]?.score))values[key]=p[key].score;
-  if(Number.isFinite(p.score))values.score=p.score;
-  for(const m of p.secondaries||[])if(Number.isFinite(m.score))values[`mission:${m.name}`]=m.score;
-  for(const m of p.primaryObjectives||[]){
-   if(m.checked!=null)values[`checked:${m.name}`]=Number(m.checked);
-   if(Number.isFinite(m.counter))values[`counter:${m.name}`]=m.counter;
-  }
-  for(const [key,value] of Object.entries(values)){
-   if(Number.isFinite(old[key]) && value>old[key])activity=true;
-   next[key]=value;
+  let activity=false;
+  if(Array.isArray(p.secondaries)){
+   const names=[...new Set(p.secondaries.map(m=>m.name))];
+   const prior=t.cards[p.name];
+   const known=Array.isArray(prior)?prior:[];
+   const added=p.secondaries.filter(m=>m.enabled!==false && !known.includes(m.name));
+   // A complete baseline proves an addition. Otherwise a new zero-point card is
+   // useful evidence, including the first visible BOTTOM card after TOP played.
+   if(t.cardBaselines?.[p.name] && added.length)activity=true;
+   else if(Object.hasOwn(t.seen,p.name) && added.some(m=>m.score===0))activity=true;
+   t.cards[p.name]=[...new Set([...known,...names])];
+   if(p.secondariesComplete){
+    t.cardBaselines=t.cardBaselines||{};
+    t.cardBaselines[p.name]=true;
+   }
   }
-  t.seen[p.name]=next;
+  t.seen[p.name]=true;
   if(activity)events.push(p.name);
  }
  if(events.length===1){
   const name=events[0];
-  if(!t.firstPlayer && t.eligible)t.firstPlayer=name;
-  t.activePlayer=name;
-  // Bottom is terminal for this round: delayed scoring cannot rewind it.
+  // Late card changes by TOP must not rewind a round after BOTTOM began.
+  if(t.half!=='bottom')t.activePlayer=name;
+  // Bottom is terminal for this round.
   if(t.firstPlayer && t.half!=='bottom')t.half=name===t.firstPlayer?'top':'bottom';
-  t.reason=t.half?'Turno inferido por actividad de puntuación':`Actividad de ${name}; esperando conocer el orden de juego`;
+  t.reason='Turno identificado por nuevas secundarias; orden de Tabletop Battles';
  }
  if(events.length>1)t.reason='Cambios en ambos jugadores; se conserva el último turno detectado';
  return t;

package/youtube/auth.js

@@ -0,0 +1,71 @@
+const fs=require('node:fs');
+const path=require('node:path');
+const os=require('node:os');
+const http=require('node:http');
+const crypto=require('node:crypto');
+const {spawn}=require('node:child_process');
+const SCOPE='https://www.googleapis.com/auth/youtube.readonly';
+const credentialDir=()=>path.join(os.homedir(),'.config','wargaming-overlay','youtube');
+function privateWrite(file,value){
+ fs.mkdirSync(path.dirname(file),{recursive:true,mode:0o700});
+ const tmp=file+'.'+crypto.randomBytes(6).toString('hex')+'.tmp';
+ try{fs.writeFileSync(tmp,JSON.stringify(value),{mode:0o600,flag:'wx'});fs.renameSync(tmp,file);}finally{try{fs.unlinkSync(tmp)}catch{}}
+}
+function read(file){try{return JSON.parse(fs.readFileSync(file,'utf8'))}catch(e){if(e.code==='ENOENT')return null;throw Error('No se pueden leer las credenciales locales de YouTube.');}}
+function clientConfig(json){
+ const c=json?.installed;
+ if(!c?.client_id || !c.client_secret)throw Error('Usa el JSON OAuth de tipo Aplicación de escritorio de Google.');
+ return {client_id:c.client_id,client_secret:c.client_secret};
+}
+class Auth {
+ constructor({dir=credentialDir(),fetchImpl=fetch,now=Date.now}={}){this.dir=dir;this.fetch=fetchImpl;this.now=now;this.pending=null;}
+ load(){const c=read(path.join(this.dir,'client.json'));if(!c)throw Error('Configura OAuth: wargaming-overlay youtube-auth --client-secret /ruta/client.json');return c;}
+ async exchange(params,signal){
+  const response=await this.fetch('https://oauth2.googleapis.com/token',{method:'POST',body:new URLSearchParams(params),signal:signal?AbortSignal.any([signal,AbortSignal.timeout(20000)]):AbortSignal.timeout(20000)});
+  const data=await response.json();
+  if(!response.ok || !data.access_token)throw Error(data.error==='invalid_grant'?'Autorización revocada o vencida. Ejecuta youtube-auth de nuevo.':'No se pudo obtener autorización de Google; se reintentará.');
+  return data;
+ }
+ save(data,old={}){
+  const tokens={refresh_token:data.refresh_token||old.refresh_token,access_token:data.access_token,expires_at:this.now()+Number(data.expires_in||3600)*1000,scope:data.scope||old.scope||SCOPE};
+  if(!tokens.refresh_token)throw Error('Google no entregó refresh token. Autoriza de nuevo con youtube-auth.');
+  if(!tokens.scope.split(' ').includes(SCOPE))throw Error('No se concedió el permiso de lectura de YouTube.');
+  privateWrite(path.join(this.dir,'tokens.json'),tokens);return tokens;
+ }
+ async token(signal){
+  const t=read(path.join(this.dir,'tokens.json'));
+  if(!t?.refresh_token)throw Error('YouTube sin autorizar. Ejecuta wargaming-overlay youtube-auth --client-secret /ruta/client.json');
+  if(t.access_token && t.expires_at>this.now()+60000)return t.access_token;
+  if(!this.pending)this.pending=(async()=>{const c=this.load();return this.save(await this.exchange({...c,grant_type:'refresh_token',refresh_token:t.refresh_token},signal),t).access_token;})().finally(()=>{this.pending=null;});
+  return this.pending;
+ }
+ invalidate(){const file=path.join(this.dir,'tokens.json'),t=read(file);if(t)privateWrite(file,{...t,expires_at:0});}
+ async authorize(clientFile,{open=url=>{const child=spawn(process.platform==='darwin'?'open':process.platform==='win32'?'explorer.exe':'xdg-open',[url],{stdio:'ignore',shell:false});child.on('error',()=>{});child.unref();},log=console.log,timeoutMs=180000}={}){
+  const c=clientFile?clientConfig(read(path.resolve(clientFile))):this.load();
+  const state=crypto.randomBytes(24).toString('hex'),verifier=crypto.randomBytes(32).toString('base64url');
+  const challenge=crypto.createHash('sha256').update(verifier).digest('base64url');
+  let resolveCode,rejectCode;
+  const codePromise=new Promise((resolve,reject)=>{resolveCode=resolve;rejectCode=reject;});
+  const server=http.createServer((req,res)=>{
+   const u=new URL(req.url,'http://127.0.0.1');
+   res.setHeader('Content-Type','text/plain; charset=utf-8');res.setHeader('Cache-Control','no-store');
+   if(u.pathname!=='/oauth/callback'){res.writeHead(404);res.end();return;}
+   if(u.searchParams.get('state')!==state){res.writeHead(400);res.end('Solicitud no válida.');return;}
+   if(u.searchParams.get('error')){res.end('Autorización cancelada. Vuelve a la terminal.');rejectCode(Error('Autorización cancelada por el usuario.'));return;}
+   const code=u.searchParams.get('code');if(!code){res.writeHead(400);res.end('Falta autorización.');return;}
+   res.end('Autorización recibida. Puedes cerrar esta ventana y volver a la terminal.');resolveCode(code);
+  });
+  await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(0,'127.0.0.1',resolve);});
+  const timer=setTimeout(()=>rejectCode(Error('Se agotó el tiempo de autorización. Ejecuta youtube-auth de nuevo.')),timeoutMs);
+  const redirect=`http://127.0.0.1:${server.address().port}/oauth/callback`;
+  try{
+   const url=new URL('https://accounts.google.com/o/oauth2/v2/auth');url.search=new URLSearchParams({client_id:c.client_id,redirect_uri:redirect,response_type:'code',scope:SCOPE,access_type:'offline',prompt:'consent',state,code_challenge:challenge,code_challenge_method:'S256'});
+   log('[YouTube] Autoriza el canal en el navegador. Si no se abre: '+url.href);open(url.href);
+   const code=await codePromise;
+   const tokens=await this.exchange({...c,code,redirect_uri:redirect,grant_type:'authorization_code',code_verifier:verifier});
+   this.save(tokens);privateWrite(path.join(this.dir,'client.json'),c);
+   log('[YouTube] Autorización guardada. Ya puedes iniciar el backend con YOUTUBE_CHAT_TTS_ENABLED=true.');
+  }finally{clearTimeout(timer);server.close();server.closeAllConnections();}
+ }
+}
+module.exports={Auth,credentialDir,privateWrite,SCOPE};

package/youtube/chat.proto

@@ -0,0 +1,29 @@
+// Minimal wire-compatible subset of the official YouTube streaming schema.
+// https://developers.google.com/youtube/v3/live/streaming-live-chat
+syntax = "proto2";
+package youtube.api.v3;
+service V3DataLiveChatMessageService {
+ rpc StreamList(LiveChatMessageListRequest) returns (stream LiveChatMessageListResponse) {}
+}
+message LiveChatMessageListRequest {
+ optional string live_chat_id = 1;
+ optional string page_token = 99;
+ repeated string part = 100;
+}
+message LiveChatMessageListResponse {
+ optional string offline_at = 2;
+ optional string next_page_token = 100602;
+ repeated LiveChatMessage items = 1007;
+}
+message LiveChatMessage {
+ optional string id = 101;
+ optional LiveChatMessageSnippet snippet = 2;
+ optional LiveChatMessageAuthorDetails author_details = 3;
+}
+message LiveChatMessageAuthorDetails { optional string display_name = 103; }
+message LiveChatMessageSnippet {
+ optional int32 type = 1;
+ optional string published_at = 4;
+ optional LiveChatTextMessageDetails text_message_details = 19;
+}
+message LiveChatTextMessageDetails { optional string message_text = 1; }

package/youtube/index.js

@@ -0,0 +1,20 @@
+const fs=require('node:fs'),path=require('node:path');
+function configFor(dataDir,env=process.env){
+ let file={};try{file=JSON.parse(fs.readFileSync(path.join(dataDir,'youtube-tts.json'),'utf8'));}catch(e){if(e.code!=='ENOENT')throw Error('Configuración youtube-tts.json inválida.');}
+ const config={enabled:true,maxMessageLength:300,maxQueueLength:10,readUsername:true,filterUrls:true,extraBlockedTerms:[],...file};
+ for(const [key,min,max] of [['maxMessageLength',50,300],['maxQueueLength',1,100]])if(!Number.isInteger(config[key])||config[key]<min||config[key]>max)throw Error(`Configuración ${key} fuera de rango.`);
+ for(const key of ['enabled','readUsername','filterUrls'])if(typeof config[key]!=='boolean')throw Error(`Configuración ${key} debe ser true/false.`);
+ if(!Array.isArray(config.extraBlockedTerms)||config.extraBlockedTerms.some(t=>typeof t!=='string'||t.length>100))throw Error('extraBlockedTerms debe ser una lista de textos cortos.');
+ return config;
+}
+function startYouTube(dataDir,{env=process.env,platform=process.platform,log=console.log}={}){
+ if(env.YOUTUBE_CHAT_TTS_ENABLED!=='true'){log('[YouTube] Chat TTS desactivado. Actívalo con YOUTUBE_CHAT_TTS_ENABLED=true.');return null;}
+ try{
+  if(platform!=='darwin')throw Error('El TTS local requiere macOS.');
+  const config=configFor(dataDir,env);if(!config.enabled){log('[YouTube] TTS desactivado en configuración.');return null;}
+  const {YouTubeService}=require('./service');
+  log('[YouTube] Iniciando chat TTS. Si falta autorización, ejecuta wargaming-overlay youtube-auth --client-secret /ruta/client.json.');
+  return new YouTubeService({config,log}).start();
+ }catch(e){log('[YouTube] '+e.message+' El overlay continúa funcionando.');return null;}
+}
+module.exports={startYouTube,configFor};

package/youtube/live-broadcast.js

@@ -0,0 +1,13 @@
+async function findBroadcast(auth,{signal,fetchImpl=fetch}={}){
+ const token=await auth.token(signal);
+ const url=new URL('https://www.googleapis.com/youtube/v3/liveBroadcasts');
+ // API accepts exactly one filter: active, NOT active + mine.
+ url.search=new URLSearchParams({part:'snippet,status',broadcastStatus:'active',broadcastType:'all',maxResults:'50'});
+ const response=await fetchImpl(url,{headers:{Authorization:`Bearer ${token}`},signal:signal?AbortSignal.any([signal,AbortSignal.timeout(20000)]):AbortSignal.timeout(20000)});
+ if(response.status===401){auth.invalidate();throw Error('Autorización vencida; renovando.');}
+ if(!response.ok)throw Error(`Consulta de directos falló (HTTP ${response.status}). Revisa permisos/cuota de YouTube.`);
+ const data=await response.json();
+ const active=(data.items||[]).filter(b=>b.snippet?.liveChatId).sort((a,b)=>String(a.id).localeCompare(String(b.id)));
+ return active[0]?{id:active[0].id,liveChatId:active[0].snippet.liveChatId,title:active[0].snippet.title,multiple:active.length>1}:null;
+}
+module.exports={findBroadcast};

package/youtube/live-chat.js

@@ -0,0 +1,22 @@
+const path=require('node:path');
+function normalize(item){
+ if(item.snippet?.type!==1 || !item.id || typeof item.snippet.textMessageDetails?.messageText!=='string')return null;
+ return {id:item.id,type:'youtube_chat_message',author:item.authorDetails?.displayName||'Usuario',text:item.snippet.textMessageDetails.messageText,timestamp:item.snippet.publishedAt,messageType:'textMessageEvent'};
+}
+async function* streamChat({auth,liveChatId,pageToken,signal,createClient}){
+ const grpc=require('@grpc/grpc-js'),loader=require('@grpc/proto-loader');
+ const def=loader.loadSync(path.join(__dirname,'chat.proto'));
+ const Service=grpc.loadPackageDefinition(def).youtube.api.v3.V3DataLiveChatMessageService;
+ const client=createClient?createClient(Service,grpc):new Service('youtube.googleapis.com:443',grpc.credentials.createSsl());
+ let call;
+ const cancel=()=>call?.cancel();
+ try{
+  const token=await auth.token(signal);if(signal?.aborted)return;
+  const meta=new grpc.Metadata();meta.set('authorization',`Bearer ${token}`);
+  // Reopen periodically with fresh credentials, retaining the continuation token.
+  call=client.streamList({liveChatId,pageToken,part:['id','snippet','authorDetails']},meta,{deadline:Date.now()+45*60*1000});
+  signal?.addEventListener('abort',cancel,{once:true});
+  for await(const batch of call)yield batch;
+ }finally{signal?.removeEventListener('abort',cancel);call?.cancel();client.close();}
+}
+module.exports={streamChat,normalize};

package/youtube/service.js

@@ -0,0 +1,64 @@
+const {EventEmitter}=require('node:events');
+const {setTimeout:delay}=require('node:timers/promises');
+const {Auth}=require('./auth');
+const {findBroadcast}=require('./live-broadcast');
+const {streamChat,normalize}=require('./live-chat');
+const {SpeechQueue}=require('../tts/queue');
+const {sanitize}=require('../tts/sanitizer');
+const backoff=[1000,2000,5000,10000,30000];
+class YouTubeService extends EventEmitter {
+ constructor({config={},auth=new Auth(),discover=findBroadcast,stream=streamChat,queue,log=console.log,sleep=(ms,signal)=>delay(ms,null,{signal}),now=Date.now}={}){
+  super();this.config=config;this.auth=auth;this.discover=discover;this.stream=stream;this.log=log;this.sleep=sleep;this.now=now;
+  this.queue=queue||new SpeechQueue({maxQueueLength:config.maxQueueLength||10,log});this.state='DISCONNECTED';this.seen=new Set();this.controller=new AbortController();this.chat=null;this.pageToken=undefined;this.task=null;
+ }
+ status(state,message){if(this.state!==state||this.lastMessage!==message){this.state=state;this.lastMessage=message;this.log('[YouTube] '+message);}}
+ start(){if(!this.task)this.task=this.run().catch(()=>{if(!this.controller.signal.aborted)this.status('DISCONNECTED','Servicio detenido por un error inesperado; el overlay continúa.');});return this;}
+ async stop(){this.controller.abort();await this.queue.stop();await this.task;}
+ endChat(){this.chat=null;this.pageToken=undefined;this.queue.clear();this.status('WAITING_FOR_STREAM','Directo terminado o chat no disponible; buscando otro directo.');}
+ async run(){
+  const signal=this.controller.signal;let failures=0;
+  while(!signal.aborted){
+   try{
+    if(!this.chat){
+     await this.auth.token(signal);this.status('AUTHENTICATED','Autorización cargada.');
+     const broadcast=await this.discover(this.auth,{signal});
+     if(!broadcast){this.status('WAITING_FOR_STREAM','Sin directo activo con chat; volveré a comprobar en 60 segundos.');await this.sleep(60000,signal);continue;}
+     this.chat=broadcast.liveChatId;this.pageToken=undefined;this.startedAt=this.now();
+     this.log(`[YouTube] Directo detectado${broadcast.multiple?' (hay varios; se usa el primero por ID)':''}.`);
+    }
+    let ended=false;
+    this.status('CONNECTED_TO_CHAT','Conectando al chat en vivo mediante streamList…');
+    for await(const batch of this.stream({auth:this.auth,liveChatId:this.chat,pageToken:this.pageToken,signal})){
+     if(signal.aborted)break;
+     failures=0;this.status('CONNECTED_TO_CHAT','Chat conectado; esperando mensajes nuevos.');
+     if(batch.offlineAt || (batch.items||[]).some(i=>i.snippet?.type===4)){ended=true;break;}
+     for(const item of batch.items||[]){
+      if(!item.id||this.seen.has(item.id))continue;
+      this.seen.add(item.id);if(this.seen.size>1000)this.seen.delete(this.seen.values().next().value);
+      const event=normalize(item);if(!event)continue;
+      // Initial streamList replies include history: never speak pre-connection messages.
+      if(!Number.isFinite(Date.parse(event.timestamp)) || Date.parse(event.timestamp)<this.startedAt)continue;
+      const safe=sanitize(event,this.config);if(!safe)continue;
+      this.log(`[Chat] ${safe.author}: ${safe.text}`);
+      // Future consumers receive the normalized event; listener failures stay isolated.
+      try{this.emit('message',event);}catch{this.log('[YouTube] Falló un consumidor de mensajes.');}
+      this.queue.enqueue(safe);
+     }
+     this.pageToken=batch.nextPageToken||this.pageToken;
+    }
+    if(ended){this.endChat();await this.sleep(60000,signal);continue;}
+    if(!signal.aborted)throw Error('Chat connection closed');
+   }catch(e){
+    if(signal.aborted)break;
+    if(e.code===16)this.auth.invalidate();
+    if([5,9].includes(e.code)){this.endChat();await this.sleep(60000,signal);continue;}
+    if(e.code===3)this.pageToken=undefined;
+    const ms=backoff[Math.min(failures++,backoff.length-1)];
+    // Do not print upstream payloads or request objects: they may contain credentials.
+    this.status('DISCONNECTED',`Conexión/autorización no disponible${Number.isInteger(e.code)?' (código '+e.code+')':''}. Reintento en ${ms/1000}s. Si persiste, revisa OAuth, API y cuota.`);
+    await this.sleep(ms,signal);
+   }
+  }
+ }
+}
+module.exports={YouTubeService,backoff};