# Migration Plan

Este plan define el orden de migración. Debe ejecutarse de forma secuencial para reducir riesgo, preservar comportamiento y evitar reescrituras amplias sin baseline.

## Principios

- Mantener nombres públicos y comportamiento hasta completar la migración.
- Congelar comportamiento antes de mover responsabilidades.
- Eliminar legacy muerto antes de envolverlo.
- Separar boundaries antes de reescribir módulos complejos.
- Tocar overlays al final y con verificación visual.

## Secuencia

| Paso | Objetivo | Tipo |
| --- | --- | --- |
| 1 | Congelar comportamiento con screenshots de overlays, fixtures de replicants, build, typecheck y lint baseline. | Baseline |
| 2 | Quitar `example*`, regenerar schema types y eliminar `.js` redundantes en `src/shared` si no se usan. | Limpieza |
| 3 | Crear `nodecg/browser` y `nodecg/extension` sin cambiar comportamiento. | Boundary |
| 4 | Añadir schemas para replicants de packs manteniendo nombres y defaults exactos. | Contratos |
| 5 | Extraer tipos/config de packs a `shared` y ajustar `tsconfig.extension` para no duplicar. | Shared |
| 6 | Reescribir controladamente `pack-manager`. | Reescritura |
| 7 | Reescribir controladamente `usePackRegistry` y `fighting-characters`. | Reescritura |
| 8 | Dividir `useIntegration`. | Modularización |
| 9 | Dividir `Players.vue`. | Modularización |
| 10 | Dividir `Settings.vue`. | Modularización |
| 11 | Refactor suave de dashboard scoreboard para eliminar duplicación left/right. | Modularización |
| 12 | Extraer view models y helpers de overlays sin tocar CSS/markup al inicio. | Overlays |
| 13 | Añadir tests puros para normalizadores y lógica de dominio. | Tests |
| 14 | Añadir verificación visual Playwright para overlays principales. | Visual QA |

## Detalle por Fase

### 1. Congelar Comportamiento

Crear una baseline antes de refactorizar:

- Screenshots de `scoreboard`, `scoreboard-2xko` y `commentary`.
- Fixtures representativos de replicants.
- Resultado actual de build y typecheck.
- Resultado actual de lint, incluyendo los 3 errores reales conocidos.

### 2. Limpiar Dead y Stale Code

Eliminar código que no representa comportamiento productivo:

- `exampleReplicant`.
- `example.ts`.
- `ExampleType`.
- Schema de ejemplo.
- Tipos generados stale.
- `.js` redundantes en `src/shared` si se confirma que no se usan.

### 3. Crear Boundaries NodeCG

Introducir APIs sin cambiar comportamiento:

- `src/nodecg/browser/replicants.ts`
- `src/nodecg/browser/messages.ts`
- `src/nodecg/extension/replicants.ts`
- `src/nodecg/extension/messages.ts`
- `src/nodecg/extension/context.ts`

El objetivo es centralizar acceso a replicants, messages, logging y NodeCG globals.

### 4. Centralizar Contratos Realtime

Añadir schemas para:

- `installedPacks`
- `packRegistry`
- `downloadStates`
- `availableUpdates`

Los nombres y defaults deben mantenerse exactamente para no romper dashboard, extensión ni overlays.

### 5. Extraer Shared de Packs

Mover a `shared`:

- Tipos de manifest.
- Tipos de registry.
- Tipos de estado de descarga.
- Config derivada común.
- Validación ligera en boundaries.

No duplicar tipos entre extension y browser.

### 6. Reescritura Controlada de Pack Manager

Separar `pack-manager.ts` en módulos pequeños:

| Módulo | Responsabilidad |
| --- | --- |
| Registry client | Fetch y normalización del registry remoto. |
| Downloader | Descargas, progreso y errores. |
| Disk store | Lectura/escritura en disco. |
| Static mount | Exposición HTTP de assets instalados. |
| Handlers | Registro de mensajes NodeCG. |
| Replicant sync | Actualización centralizada de replicants. |

### 7. Reescritura de Pack Registry Runtime

Rehacer `usePackRegistry` y `fighting-characters` para:

- Quitar estado mutable de módulo opaco.
- Evitar `ref` en shared.
- Modelar packs instalados como estado explícito.
- Cargar manifests mediante boundaries claros.
- Eliminar comentarios que contradicen el estado real de assets.

### 8. Dividir Integraciones

Extraer `useIntegration` en piezas:

- `nodecgMessageClient`
- `oauthClient`
- `temporaryPlayers`
- `tournamentImport`

Cada pieza debe tener cleanup explícito para timers/listeners.

### 9. Dividir Players

Extraer desde `Players.vue`:

- `PlayersTable`
- `PlayerEditorDialog`
- `IntegrationImportCard`
- `ImportPlayersDialog`

La vista debe coordinar el feature, no contener la implementación completa.

### 10. Dividir Settings

Extraer desde `Settings.vue`:

- `LanguageSettings`
- `ShortcutSettings`
- `IntegrationSettings`

Mantener UI Quasar y comportamiento actual.

### 11. Refactor Suave de Scoreboard Dashboard

Eliminar duplicación left/right con subcomponentes pequeños, sin cambiar el comportamiento público ni el layout principal.

### 12. Overlays al Final

Primero extraer sin modificar presentación:

- View models.
- Helpers de flags.
- Helpers de score animation.
- Helpers de text fitting.

Después de verificar baseline visual, deduplicar internals.

### 13. Tests Puros

Añadir tests para:

- Normalizadores.
- Pack registry.
- Shortcut parsing.
- Country resolving.
- Bracket round formatting.

### 14. Verificación Visual

Añadir Playwright para overlays principales:

- `scoreboard`.
- `scoreboard-2xko`.
- `commentary`.

Debe validar screenshots o checks visuales estables antes de tocar CSS sensible.

## Clasificación de Trabajo

| Categoría | Incluye |
| --- | --- |
| Automatizable | Moves/imports, schema generation, lint autofix, snapshots. |
| Reescritura controlada | Packs y registry runtime. |
| División | `Players.vue`, `Settings.vue`, overlays. |
| Conservar | Quasar UI, Pinia, schemas, `oauth-server`, concepto de `store-sync`, layout visual de overlays. |