README.md

🎱 BINGO // AVNT-GRD

Aplicación web de Bingo estilo TV con estética Avant-Garde anti-genérica

Demo • Características • Desarrollo con IA • Tecnologías

---

📖 Descripción

BINGO // AVNT-GRD es una aplicación web de Bingo diseñada para pantallas grandes (TV/Monitor) que combina:

• 🎰 Bombo 3D animado renderizado con CSS puro (sin Three.js)
• 🔊 Audio generativo mediante Web Audio API con sonidos sintetizados
• 🗣️ Locución en español usando Speech Synthesis (TTS)
• 🎨 6 temas visuales únicos intercambiables en tiempo real
• 👥 Gestión inteligente de jugadores con cartones españoles oficiales (9x3)
• 💾 Persistencia completa en LocalStorage

El diseño sigue la filosofía "Intentional Minimalism" — rechazando estéticas genéricas de templates en favor de direcciones tonales audaces y distintivas.

---

🚀 Demo / Cómo Ejecutar

# No requiere instalación, servidor, ni dependencias externas
# Simplemente abre el archivo en tu navegador:

index.html

Requisitos

• 🌐 Navegador moderno (Chrome recomendado para mejor compatibilidad con TTS)
• 🔊 Speakers/Audio habilitado para la experiencia completa

Controles

Tecla	Acción
Espacio	Extraer bola (manual) / Play-Pause (automático)
Click en bombo	Misma función que Espacio

---

✨ Características Principales

🎰 Bombo 3D CSS Puro

Cilindro 3D modelado con 12 caras CSS, rotación continua animada, y bolas decorativas flotantes con delays aleatorios. La extracción incluye una secuencia cinematográfica: aparición → salida → giro 720° → escalado → reveal del número.

🔊 Audio Sintético + TTS

• SFX generados: Bombo girando (oscilador 40-60Hz), pop de bola (sweep 800→200Hz), fanfarrias de línea/bingo
• Locución española: "¡Treinta y tres!" con voces nativas del sistema
• Sincronización: Promesas que esperan fin de audio antes de continuar

🎨 6 Temas Visuales

Tema	Estética
☀️ Light	Estética Apple Design Language. Limpio, minimalista, con sombras suaves y acentos en Azul Apple (#007aff).
🌙 Dark	Inspirado en Android Material Dark Mode. Colores desaturados con acentos vibrantes Neon Rose (#ff2a6d).
🪵 Wood	Elegancia clásica de club profesional. Caoba rica, fieltro verde de billar y detalles en latón pulido (#c9a227).
💿 Metal	Estética Cybernetic Metal. Superficies metálicas, patrones de circuitos y neones Cian (#00f5ff) y Magenta (#ff00ff).
⚙️ Steampunk	Era Industrial Victoriana. Bronce, cobre, engranajes, cuero y medidores vintage con acentos en Bronce (#cd7f32).
🔮 Glass	Estética Crystal Chess. Cristal transparente, efectos de refracción, reflejos de diamante y desenfoque de fondo.

🎫 Cartones Españoles Oficiales

• Grid 9 columnas × 3 filas
• 5 números por fila (15 totales)
• Distribución por columnas: 1-9, 10-19, ..., 80-90
• Generación con validación de reglas oficiales

👥 Gestión de Jugadores

• Hasta 10 jugadores visibles con scroll inteligente
• Reordenación automática basada en aciertos recientes
• Mini-cartones con estado visual de números marcados
• Celebraciones fullscreen para líneas y bingos

💾 Persistencia Completa

• Configuración (tema, modo, volumen)
• Estado del juego (números extraídos, puntuación)
• Jugadores y sus cartones
• Modal "¿Continuar partida anterior?" al recargar

---

🤖 Desarrollo 100% con IA

TODO el código de este proyecto fue generado por Inteligencia Artificial

Utilizando GitHub Copilot (con modelos Claude 4.5 Opus y Gemini 3 Pro) siguiendo un plan maestro estructurado en 12 fases, también creado por IA basándose en los requisitos detallados por el usuario en Requisitos.md.

📋 El Plan Maestro

El archivo plan-bingoWebApp.md contiene:

• Arquitectura completa de archivos
• 12 fases con tareas detalladas numeradas
• Diagrama de clases y relaciones
• Especificaciones técnicas (Web Audio, TTS, CSS 3D)
• Tabla de estados e interacciones

🤖 Sistema de Agentes y Prompts

La carpeta .github/ contiene la infraestructura de prompts que permite la generación consistente:

.github/
├── copilot-instructions.md      # Instrucciones base del sistema
├── agents/
│   ├── orquestador.agent.md     # Agente gestor (NO escribe código)
│   └── front-developer.agent.md # Agente implementador
└── prompts/
    └── develop-front.prompt.md  # Template de invocación

📄 copilot-instructions.md

Define el rol base: "Senior Frontend Architect & Avant-Garde UI Designer" con 15+ años de experiencia. Establece:

• Directivas operacionales (Zero Fluff, Output First)
• Uso de herramientas MCP (SonarQube, Chrome DevTools)
• Filosofía de diseño "Intentional Minimalism"
• Protocolo "ULTRATHINK" para análisis profundo

🎭 orquestador.agent.md

Agente gestor que:

• Lee y comprende el plan maestro
• Desglosa las fases en tareas individuales
• Delega cada tarea al front-developer
• Trackea progreso con marcadores #todo / #done
• NUNCA escribe código directamente

👨‍💻 front-developer.agent.md

Agente implementador que:

• Recibe tareas aisladas del orquestador
• Escribe código production-ready
• Valida con SonarQube MCP (quality/security)
• Verifica con Chrome DevTools (functional)
• Reporta estado al orquestador

📝 develop-front.prompt.md

Template para invocar al front-developer con contexto aislado y estructura consistente.

🔄 Flujo de Trabajo

┌─────────────────────────────────────────────────────────────────┐
│                         FLUJO DE DESARROLLO                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   👤 Usuario                                                    │
│      │                                                          │
│      ▼ proporciona                                              │
│   📋 Plan Maestro (.md)                                         │
│      │                                                          │
│      ▼ Cambia a modo orquestador y pide que implemente el plan  │
│   🎭 ORQUESTADOR                                                │
│      │ crea tareas #todo                                        │
│      │                                                          │
│      ▼ delega (subAgente)                                       │
│   👨‍💻 FRONT-DEVELOPER                                            │
│      │                                                          │
│      ├──▶ Implementa código                                     │
│      ├──▶ Valida con SonarQube                                  │
│      ├──▶ Verifica con DevTools                                 │
│      │                                                          │
│      ▼ reporta                                                  │
│   🎭 ORQUESTADOR                                                │
│      │ marca #done                                              │
│      │                                                          │
│      ▼ siguiente tarea...                                       │
│   🔁 Repite hasta completar fase                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

📁 Estructura del Proyecto

Bingo/
├── index.html                  # Estructura semántica principal
├── plan-bingoWebApp.md         # Plan maestro del desarrollo
├── README.md                   # Este archivo
│
├── css/
│   ├── styles.css              # Layout y estilos base + variables
│   ├── animations.css          # Animaciones bombo/bolas 3D
│   ├── components.css          # Modales, botones, tarjetas, jugadores
│   ├── toast.css               # Notificaciones toast
│   └── themes/
│       ├── light.css           # ☀️ Tema claro elegante
│       ├── dark.css            # 🌙 Tema oscuro neón
│       ├── wood.css            # 🪵 Tema madera clásico
│       ├── metal.css           # ⚙️ Tema metálico industrial
│       ├── steampunk.css       # 🚂 Tema steampunk victoriano
│       └── glass.css           # 🔮 Tema glassmorphism
│
├── js/
│   ├── app.js                  # Inicialización y orquestación
│   ├── bingo-engine.js         # Lógica del juego (EventTarget)
│   ├── drum.js                 # Bombo 3D y animaciones
│   ├── cards.js                # Generación cartones españoles
│   ├── players.js              # Gestión de jugadores
│   ├── audio.js                # Web Audio API + TTS
│   ├── storage.js              # Persistencia localStorage
│   ├── settings.js             # Configuración y modal
│   └── ui.js                   # Interacciones UI
│
└── .github/
    ├── copilot-instructions.md # Instrucciones base IA
    ├── agents/
    │   ├── orquestador.agent.md
    │   └── front-developer.agent.md
    └── prompts/
        └── develop-front.prompt.md

---

🛠️ Tecnologías

Core

• HTML5 — Estructura semántica con <header>, <main>, <section>, modales
• CSS3 — Grid, Flexbox, 3D Transforms, Custom Properties, Keyframes
• JavaScript ES6+ — Modules, Classes, EventTarget, async/await

APIs del Navegador

• Web Audio API — AudioContext, OscillatorNode, GainNode para SFX sintéticos
• SpeechSynthesis API — Locución TTS en español
• LocalStorage API — Persistencia de estado

Sin Dependencias Externas

• ❌ No jQuery
• ❌ No React/Vue/Angular
• ❌ No Three.js
• ❌ No librerías de audio
• ✅ 100% Vanilla

---

🎮 Estados del Juego

Estado	Modo Manual	Modo Automático
idle	Extrae la primera bola para comenzar.	Inicia el temporizador y extrae la primera bola.
playing	Extrae la siguiente bola.	Pausa el temporizador (detiene el flujo).
paused	Extrae la siguiente bola (vuelve a playing).	Reanuda el temporizador (continúa el flujo).
celebrating	Cierra la celebración y permite extraer la siguiente.	Cierra la celebración y reanuda el flujo automático.
finished	El juego ha terminado (90 bolas o límite de bingos).	—

---

�️ Testing y Debugging

Para propósitos de prueba y validación de las celebraciones de BINGO, es posible "trucar" el bombo desde la consola de desarrollador del navegador (F12).

Comandos de Consola

Acción	Comando
Trucar Juego	app.rigGameForPlayer(app.players.players[0].id)

Este comando identifica los números restantes del primer jugador y los mete en una cola de prioridad para que salgan en las próximas extracciones.

---

�📜 Licencia

Apache License 2.0

Copyright (c) 2026

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the Licenserge, publish, distribute, sublicense, and/or sell
copies of the Software...

---

Hecho con 🤖 por IA, para humanos

"Every element must have a purpose. If it has no purpose, delete it."