@ing.jorgeu/wargaming-overlay 2.2.0

package/LICENSE

@@ -0,0 +1,13 @@
+Zero-Clause BSD
+==============
+
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE
+FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
+DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/PUBLISHING.md

@@ -0,0 +1,35 @@
+# Preparación para npm
+
+La versión 2.1.0 está empaquetada para distribución, pero NO se ha publicado ni instalado globalmente en el equipo del usuario.
+
+## 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:
+
+```sh
+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.
+
+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.
+
+`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`.
+
+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.
+
+Fuentes oficiales: [npm publish](https://docs.npmjs.com/cli/v7/commands/npm-publish/), [Trusted Publishing](https://docs.npmjs.com/trusted-publishers/).

package/README.md

@@ -0,0 +1,471 @@
+# Wargaming Overlay
+
+Overlay local para OBS con marcador, ronda, CP, primarias y secundarias leídos de un teléfono Android. Incluye panel de configuración, vínculo de jugadores por nombre, indicadores de misión cumplida, persistencia de la partida y botón para restablecer los datos.
+
+**Paquete:** `@ing.jorgeu/wargaming-overlay` · **Comando:** `wargaming-overlay` · **Licencia del código:** 0BSD.
+
+El paquete está preparado para npm, pero no se ha publicado desde este proyecto. `@ing.jorgeu` debe corresponder a la cuenta u organización real que publique. Hasta entonces, instala desde el código fuente o un archivo `.tgz`.
+
+## Contenido
+
+- [Requisitos](#requisitos)
+- [Instalar dependencias en macOS](#macos)
+- [Instalar dependencias en Windows](#windows)
+- [Instalar dependencias en Linux](#linux)
+- [Instalar el CLI](#instalar-el-cli)
+- [Preparar el teléfono](#preparar-el-teléfono)
+- [Primer inicio y configuración de OBS](#primer-inicio-y-configuración-de-obs)
+- [Comandos y ejemplos](#comandos-y-ejemplos)
+- [Migrar, guardar y restablecer](#migrar-guardar-y-restablecer)
+- [Solución de problemas](#solución-de-problemas)
+- [Actualizar y desinstalar](#actualizar-y-desinstalar)
+- [Desarrollo y publicación](#desarrollo-y-publicación)
+
+## Requisitos
+
+| Dependencia | Requisito y función | Descarga oficial |
+| --- | --- | --- |
+| Node.js y npm | Node 20 o posterior; preferir una versión LTS mantenida. Ejecuta el CLI y servidor. npm viene con las instalaciones habituales de Node. | [Node.js](https://nodejs.org/en/download/) |
+| Python | Python 3.8 o posterior; preferir una versión mantenida. Interpreta el XML de Android. | [Python](https://www.python.org/downloads/) |
+| ADB | Android SDK Platform-Tools. Comunica el equipo con el teléfono. | [Platform-Tools](https://developer.android.com/tools/releases/platform-tools) |
+| OBS Studio | Fuente Navegador disponible. Muestra el overlay sobre el vídeo. | [OBS Studio](https://obsproject.com/download) |
+| Teléfono Android | App Tabletop Battles abierta en la ronda, opciones de desarrollador y depuración USB habilitadas. | [Conectar un dispositivo Android](https://developer.android.com/studio/run/device) |
+| Cable USB | Debe transmitir datos, no solo cargar. | — |
+
+No requiere Android Studio completo, Java, paquetes pip, OCR ni dependencias npm adicionales. No lee iPhone/iOS. Aunque el nombre del proyecto es genérico, el parser actual está adaptado a la interfaz Android de Tabletop Battles; no interpreta automáticamente otras aplicaciones.
+
+El servidor escucha únicamente en `127.0.0.1`, puerto **8765** por defecto. No necesita `sudo` ni ejecutarse como administrador. La instalación de dependencias del sistema sí puede solicitar permisos. Se necesita internet para descargar software; la lectura y el overlay funcionan localmente.
+
+**Validación:** macOS probado con un Galaxy real. Windows y Linux tienen soporte de rutas/instaladores y escenarios simulados en las pruebas. La matriz de CI está preparada para las tres plataformas; las pruebas físicas de USB en Windows/Linux siguen pendientes. No se ha medido todavía el impacto durante una transmisión real 1440p60.
+
+## macOS
+
+1. Instala [Homebrew](https://brew.sh/) siguiendo las instrucciones de su página, si quieres usarlo. Abre una nueva Terminal después de instalarlo.
+2. Instala las dependencias:
+
+   ```sh
+   brew install node python
+   brew install --cask android-platform-tools
+   ```
+
+3. Comprueba las versiones:
+
+   ```sh
+   node --version
+   npm --version
+   python3 --version
+   adb version
+   ```
+
+4. Instala OBS desde su [página oficial](https://obsproject.com/download).
+5. Continúa con [Instalar el CLI](#instalar-el-cli).
+
+Sin Homebrew, instala Node y Python desde sus páginas oficiales y descarga el ZIP de Platform-Tools para Mac. Extrae el ZIP, por ejemplo en `$HOME/Android/platform-tools`. Puedes añadir esa carpeta al PATH de esta sesión:
+
+```sh
+export PATH="$HOME/Android/platform-tools:$PATH"
+adb version
+```
+
+Para conservarlo, añade esa línea a `~/.zshrc` y abre otra Terminal. También puedes usar `--adb "$HOME/Android/platform-tools/adb"` sin modificar PATH. macOS no necesita drivers USB adicionales para ADB. [Referencia de Homebrew para ADB](https://formulae.brew.sh/cask/android-platform-tools).
+
+## Windows
+
+Los ejemplos usan **PowerShell**. Ejecuta el overlay como usuario normal.
+
+1. Instala Node.js LTS desde [Node.js](https://nodejs.org/en/download/). Incluye npm.
+2. Instala Python desde [Python para Windows](https://www.python.org/downloads/windows/), siguiendo la [guía oficial](https://docs.python.org/3/using/windows.html). Abre otra terminal al finalizar.
+3. Instala ADB con WinGet:
+
+   ```powershell
+   winget install --exact --id Google.PlatformTools --source winget
+   ```
+
+   Si no tienes WinGet, consulta [su instalación oficial](https://learn.microsoft.com/en-us/windows/package-manager/winget/), o descarga Platform-Tools para Windows desde [Google](https://developer.android.com/tools/releases/platform-tools). Extrae el ZIP, por ejemplo en `C:\Android\platform-tools`.
+
+4. Abre una nueva PowerShell y comprueba:
+
+   ```powershell
+   node --version
+   npm.cmd --version
+   python --version
+   adb version
+   ```
+
+   Si Python está instalado mediante el launcher y `python` no responde, prueba `py -3 --version`. El CLI busca `python3`, `python` y el launcher `py`.
+
+5. Si el teléfono no aparece, instala el [driver USB de su fabricante](https://developer.android.com/studio/run/oem-usb). Para Samsung, consulta el [driver oficial](https://developer.samsung.com/android-usb-driver).
+6. Instala [OBS](https://obsproject.com/download) y continúa con [Instalar el CLI](#instalar-el-cli).
+
+Si extrajiste ADB manualmente, puedes usar una ruta explícita:
+
+```powershell
+wargaming-overlay.cmd doctor --adb "C:\Android\platform-tools\adb.exe"
+```
+
+O añadirla al PATH de la sesión:
+
+```powershell
+$env:Path = "C:\Android\platform-tools;" + $env:Path
+adb version
+```
+
+Para hacer el cambio permanente, añade la carpeta a la variable **Path de tu usuario** desde las variables de entorno de Windows y abre otra terminal. Si PowerShell bloquea `npm.ps1`, usa `npm.cmd`; para el CLI usa `wargaming-overlay.cmd`. No hace falta cambiar la política de ejecución. [Referencia del instalador WinGet](https://learn.microsoft.com/en-us/windows/package-manager/winget/install).
+
+## Linux
+
+Instala las dependencias con el gestor de tu distribución. Comprueba siempre que `node --version` sea 20 o superior; si tu repositorio ofrece una versión más antigua, sigue una opción adecuada de la [guía oficial de Node.js](https://nodejs.org/en/download/).
+
+### Debian / Ubuntu
+
+```sh
+sudo apt-get update
+sudo apt-get install nodejs npm python3 adb android-sdk-platform-tools-common
+```
+
+Si ADB informa que faltan permisos USB, comprueba el grupo `plugdev`:
+
+```sh
+id -nG
+sudo usermod -aG plugdev "$USER"
+```
+
+El segundo comando es necesario solo si tu usuario no pertenece al grupo. Cierra sesión y vuelve a entrar para aplicar el cambio. Las reglas udev se incluyen en `android-sdk-platform-tools-common`. [Guía Android para Ubuntu](https://developer.android.com/studio/run/device), [paquete adb](https://packages.ubuntu.com/en/jammy/adb).
+
+### Fedora
+
+```sh
+sudo dnf install nodejs npm python3 android-tools
+```
+
+Si hay errores de permisos, revisa las reglas udev y permisos USB de tu distribución. No asumas que existe el grupo `plugdev` ni ejecutes el overlay con sudo. [Paquete android-tools de Fedora](https://packages.fedoraproject.org/pkgs/android-tools/android-tools/).
+
+### Arch Linux
+
+```sh
+sudo pacman -Syu nodejs npm python android-tools android-udev
+```
+
+Este comando actualiza el sistema además de instalar las dependencias; revisa la operación que presenta pacman. [Paquete android-tools de Arch](https://archlinux.org/packages/extra/x86_64/android-tools/).
+
+### Otras distribuciones y comprobación
+
+Instala Python 3 y ADB con tu gestor o usa [Platform-Tools oficiales](https://developer.android.com/tools/releases/platform-tools). `setup` no instala automáticamente en distribuciones sin apt-get, dnf o pacman.
+
+```sh
+node --version
+npm --version
+python3 --version
+adb version
+```
+
+Instala OBS siguiendo las [instrucciones oficiales para Linux](https://obsproject.com/kb/linux-installation) y comprueba que incluya la fuente Navegador.
+
+## Instalar el CLI
+
+Elige **una** opción. La instalación del paquete no instala ADB o Python automáticamente.
+
+### A. Desde el código fuente, disponible ahora
+
+Descarga/descomprime el proyecto, o clónalo si tienes la URL del repositorio. Abre una terminal en la carpeta que contiene `package.json`:
+
+```sh
+npm install -g .
+wargaming-overlay --version
+wargaming-overlay --help
+```
+
+En PowerShell puedes usar `npm.cmd install -g .` y `wargaming-overlay.cmd --help`.
+
+También puedes usarlo **sin instalar globalmente**, desde esa carpeta:
+
+```sh
+node cli.js doctor
+npm start
+```
+
+### B. Desde un archivo de paquete
+
+Sustituye la ruta por la del archivo que recibiste:
+
+```sh
+npm install -g "/ruta/ing.jorgeu-wargaming-overlay-2.2.0.tgz"
+```
+
+Ejemplo Windows:
+
+```powershell
+npm.cmd install -g "$HOME\Downloads\ing.jorgeu-wargaming-overlay-2.2.0.tgz"
+```
+
+### C. Desde npm, después de publicarlo
+
+```sh
+npm install -g @ing.jorgeu/wargaming-overlay
+```
+
+Ese comando requiere que el paquete ya exista en npm. Si el scope definitivo cambia, usa el nombre publicado. Un error 404 antes de publicar no significa que tu instalación de Node esté mal.
+
+### Evitar EACCES en macOS / Linux
+
+Puedes instalar en una carpeta de tu usuario, sin sudo:
+
+```sh
+npm install -g --prefix "$HOME/.local" .
+export PATH="$HOME/.local/bin:$PATH"
+wargaming-overlay --version
+```
+
+Para conservar el PATH, añade la línea `export PATH` a `~/.zshrc` si usas zsh, o `~/.bashrc` si usas bash. Abre otra terminal. En esta modalidad, usa el mismo `--prefix "$HOME/.local"` al reinstalar o desinstalar. [Documentación npm install](https://docs.npmjs.com/cli/v8/commands/npm-install/).
+
+## Preparar el teléfono
+
+1. Conecta un cable USB de datos y desbloquea el teléfono.
+2. Activa **Opciones de desarrollador**. Habitualmente: Ajustes → Acerca del teléfono → Información de software → pulsa siete veces **Número de compilación**. La ubicación depende del fabricante.
+3. En Opciones de desarrollador activa **Depuración USB**.
+4. Acepta en el teléfono **Permitir depuración USB** para tu equipo. Puedes marcar que recuerde ese equipo si es tu ordenador de confianza.
+5. Comprueba la conexión:
+
+   ```sh
+   adb devices -l
+   wargaming-overlay doctor
+   ```
+
+6. Abre Tabletop Battles en una partida y selecciona la ronda que quieres emitir. Mantén el teléfono desbloqueado y la app visible.
+
+`device` significa conectado y autorizado; `unauthorized` significa que falta aceptar el permiso; `offline` significa que ADB no puede comunicarse correctamente. Si la lista está vacía, ADB no distingue entre cable ausente, cable sin datos y depuración desactivada. [Guía oficial de conexión](https://developer.android.com/studio/run/device).
+
+## Primer inicio y configuración de OBS
+
+1. Detén cualquier lector anterior con Ctrl+C. No ejecutes dos lectores UIAutomator contra el mismo teléfono.
+2. Si tienes datos de una versión anterior, [migra antes del primer inicio](#migrar-guardar-y-restablecer).
+3. Inicia:
+
+   ```sh
+   wargaming-overlay start
+   ```
+
+4. Abre el panel en [http://127.0.0.1:8765](http://127.0.0.1:8765).
+5. Configura título, nombres, facciones, disposiciones y destacamentos. Si el nombre visible del overlay es distinto al de la app, completa **Nombre en la app** para cada jugador. Pulsa **Actualizar overlay**.
+6. En OBS añade una fuente **Navegador**, desmarca **Archivo local** y usa:
+
+   ```text
+   http://127.0.0.1:8765/overlay-art.html
+   ```
+
+7. Configura el **ancho y alto de la fuente** según tu lienzo. El selector del panel muestra las medidas; no modifica OBS por sí mismo.
+8. En el teléfono, desplázate para mostrar el nombre y los bloques de datos de cada jugador. En pocos segundos aparecerán las lecturas.
+9. Mantén la terminal abierta. Ctrl+C detiene servidor y lector; el estado queda guardado.
+
+La asignación izquierda/derecha se hace por nombre, no por posición en el teléfono. Ignora mayúsculas y espacios adicionales; no adivina apodos. Dos nombres ambiguos no se vinculan. `—` significa que no hay lectura, no cero.
+
+### Resoluciones
+
+| Formato | Ancho | Alto |
+| --- | ---: | ---: |
+| 720p | 1280 | 720 |
+| 900p | 1600 | 900 |
+| 936p | 1664 | 936 |
+| 1080p | 1920 | 1080 |
+| 1440p — referencia original | 2560 | 1440 |
+| 4K UHD | 3840 | 2160 |
+
+El diseño **original a 2560×1440** es la referencia. En las otras resoluciones se escala todo proporcionalmente: fuentes, posiciones, iconos y separaciones. No reorganiza los elementos. Se verificó la igualdad geométrica con el original a 1440p y el escalado proporcional a 720p, 1080p y 4K.
+
+Con otra relación de aspecto mantiene 16:9, centrado horizontalmente y alineado arriba, dejando espacio transparente. No hay una composición vertical dedicada. El soporte del overlay no garantiza que YouTube/Twitch acepten esa resolución para tu cuenta; configura la salida y el bitrate en OBS de forma independiente.
+
+## Comandos y ejemplos
+
+| Comando | Acción |
+| --- | --- |
+| `wargaming-overlay start` | Inicia servidor y lector. Es el comando predeterminado. |
+| `wargaming-overlay doctor` | Comprueba Python, ADB y estado del dispositivo. |
+| `wargaming-overlay setup` | Muestra la guía de tu sistema y ejecuta diagnóstico; no instala nada. |
+| `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 --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.
+
+### Opciones
+
+| Opción | Valor predeterminado | Uso |
+| --- | --- | --- |
+| `--port` | `8765` | Puerto de `start`, entero entre 1024 y 65535. |
+| `--interval` | `3` | Pausa entre lecturas de `start`, entre 1 y 60 segundos. Se suma al tiempo de captura. |
+| `--serial` | Selección automática si hay uno | Dispositivo para `start`, `doctor` o `setup`. |
+| `--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`. |
+
+Las opciones no se guardan como configuración del CLI: repítelas en futuros inicios si quieres mantener un puerto, serial o ruta distintos.
+
+Puerto alternativo y lectura menos frecuente:
+
+```sh
+wargaming-overlay start --port 8766 --interval 5
+```
+
+En OBS usa entonces `http://127.0.0.1:8766/overlay-art.html`.
+
+Varios dispositivos:
+
+```sh
+adb devices -l
+wargaming-overlay doctor --serial SERIAL_DEL_TELEFONO
+wargaming-overlay start --serial SERIAL_DEL_TELEFONO
+```
+
+Rutas explícitas, útiles si no están en PATH:
+
+```sh
+wargaming-overlay start --adb "$HOME/Android/platform-tools/adb" --python /usr/local/bin/python3
+```
+
+En Windows, sustituye las rutas de ejemplo por las reales:
+
+```powershell
+wargaming-overlay.cmd start --adb "C:\Android\platform-tools\adb.exe" --python "C:\Python312\python.exe"
+```
+
+Carpeta independiente para pruebas:
+
+```sh
+wargaming-overlay start --data-dir "./datos-de-prueba" --port 8766
+```
+
+No ejecutes esa instancia al mismo tiempo que otra que esté leyendo el mismo teléfono.
+
+## Migrar, guardar y restablecer
+
+### Migración
+
+Detén el servidor anterior. La carpeta de origen debe contener `overlay-state.json`, `game-state.json` o ambos:
+
+```sh
+wargaming-overlay migrate "/ruta/al/overlay-anterior"
+wargaming-overlay start
+```
+
+Windows:
+
+```powershell
+wargaming-overlay.cmd migrate "C:\Users\Ana\Documents\overlay-anterior"
+```
+
+La migración **copia**, no elimina el original. Se niega a sobrescribir archivos existentes en el destino. Si ya iniciaste el nuevo servidor y quieres conservar también ese estado, usa un destino nuevo:
+
+```sh
+wargaming-overlay migrate "/ruta/al/overlay-anterior" --data-dir "./partida-importada"
+wargaming-overlay start --data-dir "./partida-importada"
+```
+
+No migra archivos HTML/CSS ni imágenes personalizadas: el paquete trae sus propios recursos. Para importar esas personalizaciones se requiere trabajar sobre el código fuente.
+
+### Ubicación de los datos
+
+| Sistema | Carpeta predeterminada |
+| --- | --- |
+| macOS | `~/Library/Application Support/wargaming-overlay` |
+| Windows | `%LOCALAPPDATA%\wargaming-overlay` |
+| Linux | `$XDG_DATA_HOME/wargaming-overlay`, o `~/.local/share/wargaming-overlay` |
+
+`overlay-state.json` contiene los nombres, vínculos y apariencia. `game-state.json` guarda la última partida leída. Están fuera de la instalación npm para sobrevivir a las actualizaciones. Para hacer un respaldo consistente, detén el servidor y copia ambos archivos. Usa `--data-dir` si quieres conservar la ubicación de una instalación anterior al cambio de nombre.
+
+### Persistencia y reset
+
+Si desconectas el teléfono, abres otra pantalla o falla una captura, el overlay conserva el último estado. El panel informa del problema. Reiniciar el servidor vuelve a cargar el estado guardado.
+
+El botón **Restablecer datos de la partida** vacía los puntos y misiones guardados, sin cambiar nombres, facciones ni diseño. Si el teléfono sigue conectado, la próxima lectura volverá a completar lo visible. Restablece cuando empieces una nueva partida con los mismos jugadores.
+
+### Qué se puede leer
+
+- Marcador, nombres y ronda de la pantalla abierta.
+- CP, totales de primaria/secundaria y misiones visibles cuando se identifica su jugador.
+- Casilla marcada o pendiente en las primarias que la exponen; contador cuando la interfaz expone uno.
+- Puntos y máximo en las secundarias que los exponen.
+
+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. No infiere TOP/BOTTOM ni quién está jugando por el puntaje. El nombre general de la primaria no siempre está expuesto; se muestran sus condiciones de puntuación.
+
+## Solución de problemas
+
+| Problema | Qué hacer |
+| --- | --- |
+| `wargaming-overlay: command not found` | Comprueba la instalación con `npm list -g --depth=0`. Revisa PATH y abre otra terminal. En Unix, los ejecutables están bajo `bin` del prefijo mostrado por `npm prefix -g`; en Windows, en el propio prefijo. |
+| PowerShell bloquea un `.ps1` | Usa `npm.cmd` y `wargaming-overlay.cmd`. |
+| npm devuelve EACCES | Usa la instalación en `~/.local` descrita arriba. No inicies el servidor con sudo. |
+| npm devuelve 404 | El paquete puede no estar publicado o el scope ser distinto. Instala desde el código fuente o `.tgz`. |
+| ADB no encontrado | Ejecuta `setup --install-adb`, instala Platform-Tools o pasa `--adb` con la ruta completa. |
+| Python ausente/incompatible | Instala Python 3.8+ y usa `--python` si tienes varias instalaciones. En Windows prueba `py -3 --version`. |
+| No aparece ningún teléfono | Revisa cable de datos, puerto USB, desbloqueo y depuración USB. En Windows comprueba drivers. |
+| `unauthorized` | Desbloquea el teléfono y acepta el permiso de depuración para este equipo. Reconecta el cable si no aparece. |
+| `offline` | Desbloquea y reconecta el teléfono. |
+| `no permissions` en Linux | Revisa reglas udev y grupos. En Ubuntu instala `android-sdk-platform-tools-common` y comprueba `plugdev`. |
+| Hay varios dispositivos | Usa `adb devices -l` y pasa `--serial`. Incluye emuladores en esta comprobación. |
+| El puerto está ocupado | Detén la otra instancia o usa `--port 8766` y actualiza la URL de OBS. |
+| No se puede leer Android / error 137 | Abre la ronda, desbloquea el teléfono y cierra otros lectores UIAutomator. El CLI reintenta. |
+| Los valores están en `—` | Revisa «Nombre en la app» y muestra el nombre y bloque del jugador en la pantalla del teléfono. |
+| No cambia un dato | Desplázate para que sea visible; los valores fuera de pantalla pueden ser la última lectura guardada. |
+| OBS está vacío | Comprueba que el servidor esté abierto, que el panel responda y que la URL y puerto coincidan. Desmarca Archivo local y refresca la fuente. |
+| El diseño no refleja cambios | Refresca la fuente. Si editaste el código pero ejecutas un paquete global copiado, reinstala desde ese código. |
+| El reset se llena de nuevo | Es normal si el teléfono sigue conectado: la siguiente captura rellena los datos visibles. |
+| Migración rechazada | Ya existen archivos de estado en el destino. Usa una carpeta nueva con `--data-dir`. |
+
+## Actualizar y desinstalar
+
+Detén el servidor con Ctrl+C antes de actualizar. Desde el código fuente actualizado:
+
+```sh
+npm install -g .
+```
+
+Desde npm, cuando exista el paquete publicado:
+
+```sh
+npm install -g @ing.jorgeu/wargaming-overlay@latest
+```
+
+Si usaste un prefijo de usuario, repite `--prefix "$HOME/.local"`. Después inicia otra vez y refresca la fuente en OBS.
+
+Para desinstalar el CLI:
+
+```sh
+npm uninstall -g @ing.jorgeu/wargaming-overlay
+```
+
+O, con el prefijo de usuario:
+
+```sh
+npm uninstall -g --prefix "$HOME/.local" @ing.jorgeu/wargaming-overlay
+```
+
+La desinstalación no borra tus archivos de partida ni desinstala ADB, Python u OBS. Puedes conservar la carpeta de datos como respaldo.
+
+## Desarrollo y publicación
+
+Desde la raíz del repositorio:
+
+```sh
+npm test
+node cli.js setup --dry-run
+npm pack --dry-run
+npm pack
+```
+
+`npm pack` genera el `.tgz` instalable. `npm pack --dry-run` lista el contenido sin crear ese archivo. No hay un paso de compilación ni dependencias npm que descargar para ejecutar las pruebas; estas sí necesitan Python.
+
+La matriz de `.github/workflows/test.yml` está preparada para Node 20/22/24 en Windows, macOS y Linux. Las pruebas cubren diagnósticos, rutas, selección de instaladores, parser y estado guardado. No sustituyen las pruebas físicas de USB ni de emisión con OBS.
+
+Consulta [PUBLISHING.md](PUBLISHING.md) para autenticarte y publicar. `npm publish` sube el paquete realmente; no es un paso necesario para usarlo localmente. El scope debe ser tuyo o de una organización en la que tengas permiso. No se han incluido credenciales en el proyecto.
+
+## Licencia y recursos
+
+El código se distribuye bajo **[0BSD](LICENSE)**, una licencia permisiva que permite uso comercial, modificación y redistribución sin atribución obligatoria y sin garantías. [Texto oficial](https://opensource.org/license/0bsd).
+
+Se conservan las imágenes del overlay. Su procedencia y derechos se documentan por separado en [THIRD_PARTY_ASSETS.md](THIRD_PARTY_ASSETS.md); la licencia del código no concede derechos adicionales sobre recursos de terceros. El proyecto no declara afiliación oficial con las aplicaciones o juegos a los que hace referencia.

package/THIRD_PARTY_ASSETS.md

@@ -0,0 +1,7 @@
+# Recursos visuales
+
+Los PNG de `public/assets/` proceden del overlay local del usuario. Este proyecto no contiene documentación que establezca su autoría, licencia o permiso para redistribuirlos públicamente.
+
+Antes de publicar el paquete, el titular debe revisar los recursos y añadir las atribuciones/licencias pertinentes o reemplazarlos por recursos redistribuibles. La licencia **0BSD** del código no concede derechos sobre imágenes de terceros.
+
+Los nombres de facciones se usan como referencias descriptivas. El paquete no declara afiliación oficial.

package/battle_reader.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Local Tabletop Battles reader. Python standard library only."""
+import os, argparse, copy, functools, http.server, json, pathlib, re, subprocess, threading, time, xml.etree.ElementTree as ET
+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'))]
+    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)
+    if not header or rnd is None: raise ValueError('Abre una ronda de Tabletop Battles, sin menús encima.')
+    players = [dict(name=header[i+3], score=int(header[i+1]), cp=None, primary=None, secondary=None, secondaries=None, primaryObjectives=None) for i in range(2)]
+    names = [p['name'] for p in players]
+    if names[0] == names[1]: raise ValueError('Usa nombres distintos para identificar a los jugadores.')
+    current = None
+    section = None
+    for i, t in enumerate(texts):
+        if t in names:
+            current = players[names.index(t)]
+            section = None
+        if current is None: continue  # Never assign a clipped block to a guessed player.
+        if t.lower() == 'cp' and i and texts[i-1].isdigit(): current['cp'] = int(texts[i-1])
+        m = re.fullmatch(r'(PRIMARY|SECONDARY):\s*(\d+)/(\d+)', t)
+        if m:
+            section = m[1]
+            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]):
+                details = (None, t, texts[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})
+        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])))
+    return dict(round=rnd, half=None, players=players)
+
+def merge(previous, fresh):
+    now = time.time()
+    same = previous and previous['round'] == fresh['round'] and [p['name'] for p in previous['players']] == [p['name'] for p in fresh['players']]
+    for i, player in enumerate(fresh['players']):
+        stamps = {}
+        for key in ('cp', 'primary', 'secondary', 'secondaries'):
+            if player[key] is not None: stamps[key] = now
+            elif same:
+                player[key] = copy.deepcopy(previous['players'][i][key])
+                stamps[key] = previous['players'][i].get('observedAt', {}).get(key)
+        player['observedAt'] = stamps
+    return dict(fresh, updatedAt=now, connected=True, error=None)
+
+def save(state):
+    temp = ROOT / 'game-state.tmp'
+    temp.write_text(json.dumps(state, ensure_ascii=False, indent=2))
+    temp.replace(ROOT / 'game-state.json')
+
+def adb(serial, *args):
+    return subprocess.run([os.environ.get('OVERLAY_ADB', 'adb'), '-s', serial, *args], check=True, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=18).stdout
+
+def capture(serial):
+    adb(serial, 'shell', 'uiautomator', 'dump', '/sdcard/codex-ttba.xml')
+    return adb(serial, 'exec-out', 'cat', '/sdcard/codex-ttba.xml')
+
+class Handler(http.server.SimpleHTTPRequestHandler):
+    def do_GET(self):
+        if self.path.split('?')[0] not in ('/', '/overlay.html', '/style.css', '/overlay.js', '/game-state.json'): self.send_error(404); return
+        if self.path == '/': self.path = '/overlay.html'
+        super().do_GET()
+    def end_headers(self):
+        self.send_header('Cache-Control', 'no-store'); super().end_headers()
+    def log_message(self, *args): pass
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument('--serial'); p.add_argument('--interval', type=float, default=3)
+    p.add_argument('--port', type=int, default=8765); p.add_argument('--once', action='store_true')
+    args = p.parse_args()
+    devices = subprocess.run(['adb', 'devices'], capture_output=True, text=True, check=True).stdout
+    serials = [line.split()[0] for line in devices.splitlines() if '\tdevice' in line]
+    serial = args.serial or (serials[0] if len(serials) == 1 else None)
+    if not serial: p.error('Conecta y autoriza exactamente un teléfono, o usa --serial.')
+    state = None
+    if not args.once:
+        server = http.server.ThreadingHTTPServer(('127.0.0.1', args.port), functools.partial(Handler, directory=str(ROOT)))
+        threading.Thread(target=server.serve_forever, daemon=True).start()
+        print(f'Overlay: http://127.0.0.1:{args.port}/overlay.html · Ctrl+C para detener', flush=True)
+    try:
+        while True:
+            start = time.monotonic()
+            try:
+                state = merge(state, parse(capture(serial)))
+                save(state)
+                print(f"Ronda {state['round']}: " + ' / '.join(f"{x['name']} {x['score']}" for x in state['players']), flush=True)
+            except (ValueError, ET.ParseError, subprocess.SubprocessError, OSError) as e:
+                print(str(e), flush=True)
+                if state: state.update(connected=False, error=str(e)); save(state)
+                if args.once: raise
+            if args.once: break
+            time.sleep(max(1, args.interval - (time.monotonic() - start)))
+    except KeyboardInterrupt: pass
+
+if __name__ == '__main__': main()