refactor(algorithms): split all 30 into separate documented classes and add flowchart

Author: javiluli

README.md

@@ -1,10 +1,12 @@
 # Array Sort Visualizer · JavaFX
 
-Visualizador de **30 algoritmos de ordenación y 8 diseños gráficos** con interfaz nativa JavaFX en negro y grafito. La rama `refactor/ui-modernization` contiene una versión modernizada y completamente separada del antiguo código Swing.
+Visualizador de **30 algoritmos de ordenación y 8 diseños gráficos** con interfaz nativa JavaFX en negro y grafito. La rama `refactor/ui-modernization` está separada del antiguo código Swing.
+
+**[Ver el diagrama de flujo y la explicación de la arquitectura](docs/architecture.md)** · [Auditoría técnica](docs/audit.md)
 
 ## Ejecutar la aplicación
 
-**Requisitos:** JDK 21 y Apache Maven. Maven descarga JavaFX con sus bibliotecas nativas; no necesitas instalar el SDK por separado.
+**Requisitos:** JDK 21 y Apache Maven. Maven descarga JavaFX y sus bibliotecas nativas; no necesitas instalar el SDK por separado.
 
 ```bash
 git clone https://github.com/javiluli/array-sort-visualizer-V2.git
@@ -14,57 +16,56 @@ mvn clean package
 mvn javafx:run
 ```
 
-Si ya tienes el repositorio clonado, ejecuta `git pull` antes de compilar. En Windows, comprueba que `java -version` y `mvn -version` utilizan JDK 21. La entrada normal es `visualizer.fx.Launcher`; `PreviewLauncher` existe únicamente para generar la captura automática usada por CI.
-
-El JAR de Maven contiene las clases de la aplicación, pero no incluye un runtime JavaFX autónomo. Hasta preparar una distribución empaquetada, inicia la aplicación con `mvn javafx:run`.
+Si ya tienes la rama seleccionada, usa `git pull` antes de compilar. En Windows comprueba que `java -version` y `mvn -version` apuntan a JDK 21. La entrada normal es `visualizer.fx.Launcher`; `PreviewLauncher` solo genera una captura para CI y termina. El JAR no incluye un runtime JavaFX autónomo.
 
 ## Controles
 
-- **Algoritmo y diseño:** desplegables para los 30 algoritmos y los ocho modos gráficos.
+- **Algoritmo y diseño:** desplegables para 30 algoritmos y ocho modos gráficos.
 - **Arcoíris:** switch de activación/desactivación.
-- **Retardo:** 1–100 ms en pasos de 1 ms.
-- **Elementos:** potencias de dos entre 2 y 1024.
-- **Acciones:** ordenar, desordenar y saltar la animación. Saltar acelera la ejecución hasta terminar; no cancela el algoritmo.
-- **Información:** tiempo, cambios, accesos al array, memoria, diálogo de información y enlaces externos.
-
-Bogo sort es deliberadamente no determinista y puede tardar mucho con cantidades grandes de elementos.
-
-## Organización del proyecto
-
-El proyecto usa la estructura Maven estándar y **ya no contiene las antiguas jerarquías `Adicionales`, `Ordenar` o `Principal` ni dependencias Swing/AWT**.
+- **Retardo y elementos:** mismo control numérico con botones `− / +`; 1–100 ms y potencias de dos entre 2 y 1024.
+- **Acciones:** ordenar, desordenar y saltar animación. Saltar elimina el retardo, no cancela el cálculo.
+- **Información:** tiempo, cambios, accesos al array, memoria, diálogo de información y enlaces.
+
+Bogo sort no tiene una duración acotada y puede tardar mucho con arrays grandes.
+
+## Estructura y responsabilidades
+
+```text
+src/
+├── main/
+│   ├── java/visualizer/
+│   │   ├── core/
+│   │   │   ├── AlgorithmCatalog.java
+│   │   │   ├── SortAlgorithm.java
+│   │   │   ├── SortContext.java
+│   │   │   └── algorithms/          # 30 clases, un algoritmo por archivo
+│   │   │       ├── BubbleSort.java
+│   │   │       ├── QuickSort.java
+│   │   │       ├── ...
+│   │   │       └── SortHelpers.java # solo operaciones comunes
+│   │   └── fx/                      # JavaFX, ejecución, controles y dibujo
+│   └── resources/visualizer/fx/theme.css
+└── test/java/visualizer/fx/SortEngineRegressionTest.java
+```
 
-| Ruta | Responsabilidad |
-| --- | --- |
-| `src/main/java/visualizer/core/AlgorithmCatalog.java` | Registro único y ordenado de los 30 algoritmos. |
-| `src/main/java/visualizer/core/Algorithms.java` | Implementaciones de los algoritmos sin dependencias de interfaz gráfica. |
-| `src/main/java/visualizer/core/SortAlgorithm.java` | Contrato funcional común de los algoritmos. |
-| `src/main/java/visualizer/core/SortContext.java` | Métricas, lecturas/escrituras e hitos de animación. |
-| `src/main/java/visualizer/fx/SortEngine.java` | Worker, ciclo de vida, snapshots, shuffle y animación final. |
-| `src/main/java/visualizer/fx/VisualizerApp.java` | Composición de la interfaz y acciones JavaFX. |
-| `src/main/java/visualizer/fx/UiControls.java` | Controles reutilizables del panel lateral. |
-| `src/main/java/visualizer/fx/VisualizationCanvas.java` | Renderizado de los ocho modos y caché de colores. |
-| `src/main/resources/visualizer/fx/theme.css` | Tema visual. |
-| `src/test/java/visualizer/fx/SortEngineRegressionTest.java` | Regresión del motor y de los 30 algoritmos. |
-| `docs/audit.md` | Decisiones y límites de la auditoría técnica. |
+`AlgorithmCatalog` vincula cada nombre visible con su clase; `SortEngine` gestiona el trabajador y los snapshots; `SortContext` cuenta operaciones y permite animar sin que los algoritmos dependan de JavaFX. `VisualizationCanvas` dibuja los ocho modos. El proyecto compila íntegramente con Java 21 y UTF-8, sin fuentes Swing heredadas.
 
-Toda la aplicación se compila ahora como **Java 21 / UTF-8** mediante Maven. Ya no existe una compilación secundaria en Windows-1252 ni una capa de compatibilidad Swing.
+En [docs/architecture.md](docs/architecture.md) hay un **diagrama del recorrido completo** y un ejemplo explicado paso a paso.
 
-## Compilar, probar y documentar
+## Compilar y probar
 
 ```bash
 mvn clean package
 ```
 
-El build compila la aplicación y genera Javadoc. GitHub Actions además ejecuta la prueba de regresión del motor, el smoke test de JavaFX y una captura de la ventana real.
+El build compila la aplicación y genera Javadoc. GitHub Actions ejecuta además los 30 algoritmos con arrays pequeños (29 con ocho elementos; Bogo con dos), la prueba de controles JavaFX y una captura real. No representa una prueba exhaustiva de todos los tamaños o permutaciones ni sustituye la revisión visual de Windows.
 
-Para ejecutar manualmente la regresión en Windows después de compilar:
+Para repetir manualmente la regresión en Windows, después de compilar:
 
 ```powershell
 java -cp "target\classes;target\test-classes" visualizer.fx.SortEngineRegressionTest
 ```
 
-La regresión ejecuta los **30 algoritmos con arrays pequeños**: 29 sobre ocho elementos y Bogo sobre dos, además de validar límites de tamaño, shuffle, estado final y cierre del motor. Esto detecta regresiones funcionales importantes, pero no constituye una prueba matemática de todos los tamaños o permutaciones posibles.
-
 ## Algoritmos de ordenación
 
 - Bidirectional Bubble

docs/architecture.md

@@ -0,0 +1,67 @@
+# Cómo funciona el visualizador
+
+El proyecto tiene dos capas: `visualizer.core` contiene los algoritmos y su contrato, sin JavaFX; `visualizer.fx` contiene la ventana, los controles, el motor de ejecución y el dibujado. El motor une las dos capas mediante `SortContext`, no mediante dependencias de los algoritmos hacia la ventana.
+
+## Diagrama de flujo: pulsar «Ordenar»
+
+```mermaid
+flowchart TD
+    A([Usuario abre Launcher]) --> B[VisualizerApp crea la ventana y SortEngine]
+    B --> C[Usuario elige algoritmo y pulsa Ordenar]
+    C --> D{Motor libre y abierto?}
+    D -- No --> E[No inicia otra operación]
+    D -- Sí --> F[SortEngine reserva un único hilo de trabajo]
+    F --> G[AlgorithmCatalog localiza nombre y clase]
+    G --> H[Clase del algoritmo ordena int\[\] mediante SortContext]
+    H --> I{Quedan pasos?}
+    I -- Sí --> J[SortContext contabiliza lecturas y cambios]
+    J --> K[SortEngine publica una copia del array como Frame]
+    K --> L[AnimationTimer de VisualizerApp recibe el último Frame]
+    L --> M[VisualizationCanvas dibuja uno de los 8 estilos]
+    M --> I
+    I -- No --> N[SortEngine publica comprobación y estado final]
+    N --> O[VisualizerApp actualiza tiempo, métricas y botones]
+    O --> P([Listo para otra operación])
+```
+
+Las instantáneas se limitan aproximadamente a 60 por segundo. El bucle de ordenación se ejecuta en un hilo independiente: JavaFX solo lee los `Frame` y pinta la interfaz. El frame incluye copia de los valores, contadores, duración y estado. Los ocho dibujos no conocen los algoritmos.
+
+## Qué contiene cada carpeta
+
+```text
+src/main/java/visualizer/
+├── core/
+│   ├── AlgorithmCatalog.java       # nombres + asociación de 30 clases
+│   ├── SortAlgorithm.java          # contrato funcional
+│   ├── SortContext.java            # lecturas, escrituras, swaps y animación
+│   └── algorithms/
+│       ├── BubbleSort.java         # una implementación por archivo
+│       ├── QuickSort.java
+│       ├── ...                     # otras 28 implementaciones
+│       └── SortHelpers.java        # solo las 4 operaciones reutilizadas
+└── fx/
+    ├── Launcher.java               # entrada para usuarios
+    ├── VisualizerApp.java          # ventana y conexión de controles
+    ├── UiControls.java             # switch y steppers reutilizables
+    ├── SortEngine.java             # hilo, estado, contadores, snapshots
+    ├── VisualizationCanvas.java    # ocho dibujos
+    └── PreviewLauncher.java        # captura de CI, no app habitual
+```
+
+**Ejemplo:** al seleccionar Bubble, `VisualizerApp` llama a `SortEngine.sort(indice)`. Este consulta `AlgorithmCatalog`, que llama a `BubbleSort.sort(array, contexto)`. Bubble compara elementos; para animar intercambios usa `contexto.swap(...)`. El contexto notifica al motor, el motor publica un `Frame` y JavaFX lo dibuja. Un algoritmo diferente reutiliza exactamente ese mismo recorrido.
+
+## Por qué hay menos código que antes
+
+Antes cada algoritmo dependía de una clase llamada `MainAplicacion`, que acumulaba controles Swing, animación, contadores y estado estático. Ahora cada algoritmo contiene solo su lógica de ordenación: el `SortContext` centraliza las operaciones comunes, `SortEngine` centraliza el estado de una ejecución, `UiControls` centraliza los controles visuales y `VisualizationCanvas` centraliza el dibujo. **Se han eliminado duplicaciones y una segunda UI**, no los 30 algoritmos ni las ocho visualizaciones.
+
+## Otras acciones y límites
+
+- **Desordenar** emplea Fisher–Yates directamente en `SortEngine` y publica los mismos `Frame`.
+- **Saltar** quita el retardo de los pasos del algoritmo, pero no lo cancela. Con Bogo, esto no garantiza terminar pronto.
+- **Cambiar modo/arcoíris** solo modifica `VisualizationCanvas`; no reinicia el algoritmo.
+- **Cambiar número de elementos** reinicializa el array solo cuando el motor está libre.
+- **Memoria** se lee en JavaFX aproximadamente una vez por segundo, por separado del motor.
+
+## Cómo verificarlo
+
+`mvn clean package` compila todas las clases y genera Javadoc. GitHub Actions ejecuta una regresión de los 30 algoritmos con entradas pequeñas, una prueba de controles y una captura JavaFX. Esas pruebas no cubren todas las permutaciones ni sustituyen una prueba visual en Windows.

docs/audit.md

@@ -1,90 +1,38 @@
-# Auditoría del repositorio — rama `refactor/ui-modernization`
+# Auditoría técnica — rama `refactor/ui-modernization`
 
-Fecha: 17 de septiembre de 2026. Auditoría y refactorización completa de la rama de modernización. **No** incluye merge a `master`.
+Fecha: 17 de septiembre de 2026. Cambios exclusivos de la rama de pruebas, sin merge ni PR.
 
-## Resultado actual
+## Estructura actual
 
-La aplicación queda como un único proyecto Maven Java 21/UTF-8 con interfaz JavaFX. Se han eliminado las jerarquías antiguas `Adicionales`, `Ordenar` y `Principal`, la dependencia de Swing/AWT, la compilación secundaria en Windows-1252 y las clases puente que conservaban nombres históricos.
+Maven estándar, Java 21 y UTF-8. No existen las antiguas carpetas `Adicionales`, `Ordenar` ni `Principal`, ni la UI Swing. El motor reside en `visualizer.fx.SortEngine`; su estado ya no utiliza campos estáticos de la aplicación de 2020. Los algoritmos no importan clases UI.
 
-Se mantienen los 30 algoritmos, ocho visualizaciones, métricas, memoria, controles, enlaces, modo arcoíris y comportamiento de «Saltar ordenación».
+- `visualizer.core.AlgorithmCatalog`: fuente única de nombres y referencias a implementaciones.
+- `visualizer.core.SortAlgorithm` y `SortContext`: contrato y métricas/animación.
+- `visualizer.core.algorithms`: **30 clases con implementación propia, una por archivo**; `SortHelpers` reúne cuatro primitivas compartidas sin algoritmos seleccionables.
+- `visualizer.fx`: `Launcher`, ventana `VisualizerApp`, controles `UiControls`, motor `SortEngine`, dibujado `VisualizationCanvas` y captura CI `PreviewLauncher`.
+- `src/main/resources/visualizer/fx/theme.css`: estilos; `src/test/java/visualizer/fx/SortEngineRegressionTest.java`: regresión.
 
-## Estructura
+[Diagrama de flujo y explicación para entender las responsabilidades](architecture.md).
 
-- `src/main/java/visualizer/core/AlgorithmCatalog.java`: catálogo único de nombres e implementaciones.
-- `src/main/java/visualizer/core/Algorithms.java`: implementaciones de los 30 algoritmos.
-- `src/main/java/visualizer/core/SortAlgorithm.java`: contrato funcional común.
-- `src/main/java/visualizer/core/SortContext.java`: instrumentación compartida de accesos, cambios y checkpoints.
-- `src/main/java/visualizer/fx/SortEngine.java`: worker, ciclo de vida, snapshots, shuffle y animación final.
-- `src/main/java/visualizer/fx/VisualizerApp.java`: composición y eventos de la interfaz.
-- `src/main/java/visualizer/fx/UiControls.java`: controles reutilizables.
-- `src/main/java/visualizer/fx/VisualizationCanvas.java`: renderizado de los ocho modos.
-- `src/main/resources/visualizer/fx/theme.css`: tema visual.
-- `src/test/java/visualizer/fx/SortEngineRegressionTest.java`: regresión funcional del motor.
+## Refactorizaciones y errores revisados
 
-Esta separación evita que los algoritmos conozcan JavaFX. Solo reciben un `SortContext` y operan sobre el array.
+El registro con referencias a métodos permite detectar referencias a implementaciones inexistentes al compilar. Separar cada algoritmo simplifica revisarlo y modificarlo sin tocar los demás; se conservó el cuerpo de cada implementación y su orden. Las operaciones de partición, inserción, fusión y heap están compartidas para no duplicarlas entre Quick/Intro/Tim/Merge y sus variantes.
 
-## Cambios de arquitectura aplicados
+`SortEngine` rechaza trabajo si está cerrado u ocupado, publica el resultado terminal antes de liberar el estado ocupado, usa un hilo independiente y limita los snapshots a unos 60 por segundo. El canvas conserva una paleta cacheada para evitar recalcular colores por fotograma. Maven emplea un solo compilador Java 21; CI ejecuta compilación, Javadoc, regresión, controles y captura gráfica.
 
-| Área | Antes | Ahora |
-| --- | --- | --- |
-| Algoritmos | 30 clases heredadas con dependencias a `MainAplicacion`, estado estático y paquetes históricos. | Registro único y métodos de algoritmo aislados en `visualizer.core`. |
-| UI | JavaFX más adaptadores de compatibilidad Swing. | JavaFX nativo únicamente. |
-| Estado | Contadores, delay y finalización repartidos entre clases estáticas. | Estado de ejecución propiedad de `SortEngine`. |
-| Animación | Callbacks con nombres de la antigua UI. | `SortContext` con operaciones explícitas y checkpoints. |
-| Build | Java 21 + compilación separada Java 8/Windows-1252. | Un solo build Java 21/UTF-8. |
-| Registro | Implementaciones y nombres podían estar duplicados. | `AlgorithmCatalog` es la única fuente de orden y nombres. |
-| Tests | Smoke de UI y regresión parcial evolucionada durante la migración. | Regresión que recorre los 30 algoritmos con entradas pequeñas, más smoke JavaFX. |
+## Limitaciones
 
-## Errores y riesgos revisados
+- La regresión recorre los 30 algoritmos, pero 29 usan ocho valores y Bogo usa dos: no demuestra corrección para todos los tamaños, permutaciones o casos con duplicados. Bitonic y los controles del visualizador usan potencias de dos. Algunos algoritmos de distribución solo admiten enteros no negativos, como los valores utilizados en la aplicación.
+- Los contadores `SortContext` son consistentes dentro de la nueva arquitectura pero pueden diferir del código de 2020; ciertas operaciones auxiliares (por ejemplo la ordenación interna de cubetas) no se instrumentan paso a paso.
+- Bogo puede tardar indefinidamente. «Saltar» acelera animación, **no** es cancelación real.
+- Las pruebas UI corren en un escritorio virtual Linux; escalado DPI y tipografías de Windows requieren revisión manual.
+- `PreviewLauncher` utiliza `java.awt.image.BufferedImage` únicamente para guardar la captura PNG de CI; la interfaz de usuario y los algoritmos no utilizan Swing/AWT.
 
-### Ciclo de vida del motor
-
-El motor rechaza nuevas tareas cuando está cerrado u ocupado, publica el frame terminal antes de liberar `busy`, utiliza un worker daemon único y conserva el resultado final visible. `close()` es idempotente y una interrupción se propaga como error de ejecución en vez de ignorarse silenciosamente.
-
-### Estado global
-
-Se eliminó el estado estático compartido que impedía razonar sobre una ejecución de forma aislada. Contadores, delay, progreso de finalización y array pertenecen ahora a la instancia de `SortEngine`.
-
-### Registro de algoritmos
-
-Los nombres y funciones viven juntos en `AlgorithmCatalog`, evitando dos listas paralelas. El selector consume directamente ese catálogo.
-
-### Renderizado
-
-`VisualizationCanvas` sigue reutilizando la paleta de colores por tamaño de array y limita las actualizaciones del motor a aproximadamente 60 snapshots por segundo. No se afirma una mejora porcentual de rendimiento sin perfilado específico.
-
-### Build
-
-Maven compila todas las fuentes con Java 21 y UTF-8. Ya no existe Ant embebido ni una ruta de compilación distinta para código antiguo. Javadoc forma parte del build.
-
-## Limitaciones que siguen siendo reales
-
-### Cobertura algorítmica
-
-La regresión ejecuta los 30 algoritmos, pero usa entradas pequeñas: 29 con ocho elementos y Bogo con dos. Esto detecta regresiones comunes y errores de ordenación, pero no prueba todas las permutaciones, tamaños ni costes extremos.
-
-### Bogo sort
-
-Bogo es deliberadamente no determinista. Con tamaños grandes puede tardar indefinidamente. «Saltar ordenación» elimina el retraso de animación, pero no transforma Bogo en un algoritmo acotado ni cancela la operación.
-
-### Métricas
-
-Los contadores de cambios y accesos se instrumentan ahora mediante `SortContext`. Son coherentes dentro de la nueva arquitectura, pero no deben interpretarse como una reproducción bit a bit de los contadores históricos porque la implementación antigua no aplicaba una política uniforme en todos los algoritmos.
-
-### Revisión visual de Windows
-
-GitHub Actions usa Linux con escritorio virtual. El smoke test comprueba arranque, controles, ocho modos y una ordenación real, pero no sustituye una revisión manual del escalado DPI, tipografía y comportamiento de ventana en Windows.
-
-## Comprobaciones reproducibles
+## Cómo reproducir comprobaciones
 
 ```bash
 mvn clean package
-java -cp "target/classes;target/test-classes" visualizer.fx.SortEngineRegressionTest
 mvn javafx:run
 ```
 
-En Linux el separador de classpath es `:` en lugar de `;`.
-
-GitHub Actions además ejecuta el smoke test JavaFX y captura una imagen de la ventana real como artefacto.
-
-Todo permanece aislado en `refactor/ui-modernization`; no se ha realizado merge ni se ha abierto una pull request.
+Tras compilar, en Windows: `java -cp "target\classes;target\test-classes" visualizer.fx.SortEngineRegressionTest` (en Linux, separador `:`). GitHub Actions ejecuta además el smoke de los controles, dibujo y captura.