pippygames/docs/HANDOFF-2026-10-06.md

Handoff de games2 — 6 de octubre de 2026

Documento para retomar el 7 de octubre de 2026 en un proyecto de Codex separado del proyecto original games. Abrir el directorio local existente G:\dev\svelte\games2. El usuario ha autorizado cerrar la sesión con commit y push de todo el trabajo del repositorio en main; verificar el commit de cierre y el estado de Git al retomar. No crear otra carpeta games2 ni arrancar desde el commit inicial omitiendo los cambios de esta sesión.

Estado real del proyecto

games2 es un repositorio y aplicación independientes de G:\dev\svelte\games. Tiene un backend Go y un frontend Svelte 5/TypeScript. Hoy la base ejecutable ofrece GET /live, GET /ready, GET /api/v2/bootstrap y GET /api/v2/catalog; el catálogo aparece vacío porque todavía no hay juegos propios instalados/publicados. La API local usa 127.0.0.1:8082; Vite usa 127.0.0.1:4174 y envía /api a Go. El README explica cómo arrancarlos.

Todavía no funcionan identidad, salas, chat, motor Go, PostgreSQL, tiempo real, pantallas compartidas ni despliegue de producción de games2. /ready informa de la fase foundation; no certifica que el producto esté listo para usuarios. Los contratos de docs/ son destino de diseño salvo donde se indique expresamente que hay implementación. No confundir la producción de games v1, basada en Node, con este proyecto.

La portada actual y sus estilos son un prototipo visual rechazado/no aprobado. El usuario decidió detener diseño visual y sistema de tokens para encargarlos después a un equipo. No continuar la dirección estética actual como si fuese definitiva. Sí existe un selector español/inglés y negociación básica del catálogo; el resto de la plataforma y de los juegos todavía necesita localización.

Decisiones del usuario que deben mantenerse

• Tres capas lógicas: API Go, servidor/motor propio Go y frontend Svelte. API y servidor pueden empezar en un mismo binario modular; los límites entre capas siguen siendo explícitos.
• Solo el equipo publica juegos propios. No hay publicación de terceros ni marketplace. El motor es propio; el formato y protocolo de juegos separan reglas, presentación, recursos, componentes (barajas, dados, tableros, etc.), eventos y animaciones.
• El alcance gráfico es 2D, incluida perspectiva de mesa/isométrica, con sprites y animaciones sencillas. El usuario no contempla 3D, Three.js, iluminación o efectos avanzados, cuestiona el peso de Phaser y pide comparar Konva con Motion y su motor propio en vicen. Evaluar primero reutilización del motor propio para cartas/fichas DOM; Konva queda condicionado a necesitar dibujo y objetos Canvas, con Phaser como alternativa de mayor alcance, sin selección o integración aprobada. Svelte mantiene interfaz/controles, Go reglas/resultados y un adaptador conserva recuperación/cancelación del coordinador visual propio. Medir tamaño y consumo reales antes de afirmar ligereza. WebGL no es obligatorio y 2D/Canvas/DOM por sí solos no garantizan compatibilidad en TV/Cast.
• Protección del menor transversal: chat desactivado para menores y salas protegidas; chat adulto solo con mayoría acreditada, teléfono verificado por SMS y permisos vigentes. SMS no acredita edad. Nombres, medios, invitaciones, vistas y datos también requieren proyecciones seguras.
• Cada juego declara sus modos y presentaciones: TVBoard muestra desarrollo público en TV y controles por etapa/privados en móvil; Desktop/Mobil muestran estado autorizado y controles completos. La mesa presencial se crea con QR de entrada, sin invitaciones. En sala convencional se puede introducir invitación en Smart TV y enlazar su TV personal con un QR de mando; debe poder pasar a móvil completo conservando plaza/recibos y revocando esa TV. Los vínculos común/personal tienen alcance propio; ninguna TV ocupa plaza o envía comandos. El gesto de agitar solicita una acción con botón/teclado alternativos; Go decide azar/resultado. Todo pertenece a v2 propuesto, sin esquemas ejecutables/runtime.
• La distribución negocia player-full, player-controller y public-board por suscripción/contrato, con revisión común, reautorización y recibos independientes del dispositivo. El perfil temporal propuesto añade investigación de fuentes primarias, reloj/época y rondas con preparación, ingreso duradero, recogida y resolución. Para quiz se recomienda acierto sin premio al primer paquete; carreras compensadas con incertidumbre/empates siguen experimentales. El cambio visual durante reacción se aplica entre rondas; fallo temporal acaba sin derrota por red. No se promete medir reacción humana exacta bajo lag arbitrario.
• Los controles móviles usan la web y podrán usar después una app independiente Flutter solo de controles. El tablero en TV y las vistas completas Desktop/Mobil siguen en la web; Flutter representa únicamente player-controller de TVBoard, con datos privados necesarios para decidir. El perfil común de comunicación prepara HTTPS/WSS y SDK TypeScript/Dart con los mismos mensajes/acciones del mando. «Jugar solo en el móvil» desde Flutter abre Mobil web, autentica al mismo principal y transfiere mando/presentación conservando plaza/recibos antes de revocar la TV personal. La app no ejecuta .ts ni se conecta a Socket.IO como si fuera WebSocket simple. Sesión nativa/ticket, negociación, QR y recuperación siguen pendientes; la app se desarrolla posteriormente, sin nuevas plazas o permisos por dispositivo.
• AirConsole es el referente funcional indicado por el usuario para TV como tablero y móviles como mandos. La revisión incorporada al perfil multidispositivo recoge vinculación, controles por fase, información privada y simulador. Conservamos autoridad Go, admisión protegida y TV pasiva; no supone adoptar su SDK/servicio ni continuar el diseño visual aplazado.
• Contemplar TV no smart con Chromecast o Fire TV conectado, además de ordenador por HDMI. El perfil de acceso a pantallas distingue Silk, receptor Cast propio, duplicación y apps Google TV/Android TV/Fire TV. El dispositivo conectado ejecuta el cliente; la TV no ocupa otra plaza. Soporte real, receptor/registro Cast y apps de TV siguen pendientes; Flutter mantiene su alcance exclusivo de controles.
• Preparar desde el primer juego la posibilidad futura de 100.000 jugadores simultáneos repartidos entre salas: estado duradero, recibos/idempotencia, recuperación, límites y métricas. Esa cifra no está demostrada; añadir réplicas, transporte entre nodos o particionado corresponde a carga medida.
• La plataforma será multilingüe. La identidad visual y el sistema de tokens quedan pendientes.
• Cada juego puede admitir jugadores virtuales controlados por agentes IA. El soporte, perfiles e instrucciones deben pertenecer a las propiedades y archivos versionados del propio juego. El perfil virtual v2 propuesto está documentado, sin esquemas ni runtime; las acciones se validan como las de cualquier asiento y el agente solo recibe su información autorizada.

Documentos que guían la continuación

Tema	Documento
Estado, arranque y estructura	README
Orden de implementación	ROADMAP
Entidades, salas, seguridad y operación	Modelo de plataforma
Contratos HTTP y tiempo real	API y eventos
Arquitectura Go de tres capas	Arquitectura
Políticas de producto y menores	Políticas y protección del menor
Idiomas	Localización
Formato/protocolo v1 de juegos	Formato y protocolo, propuesta del motor y esquemas/ejemplos de docs/game-engine/
TV y móvil como superficies del juego	Perfil multidispositivo v2 propuesto
Reloj, rondas y equidad ante lag	Perfil de sincronización v2 propuesto
Web y futura app Flutter; acciones y estado bidireccionales	Perfil de comunicación de clientes v2
Modelos comunes Go/Svelte/Flutter y gestión de errores	Modelos compartidos, fuente y bindings bajo contracts/shared/
Jugadores virtuales e instrucciones dentro del juego	Perfil de agentes v2 propuesto
Preparación para 100.000 jugadores	Capacidad y escalado
Diseño visual aplazado	Exploración no aprobada
Evaluación y corrección de los documentos nuevos	Revisión del 6 de octubre

La API documentada aún usa un perfil Socket.IO v1. La arquitectura recomienda estudiar un binding WebSocket Go versionado; cambiar el transporte requiere contrato y pruebas, y no convierte automáticamente los esquemas TypeScript del motor en reglas ejecutables Go. El perfil multidispositivo agrega game.* v2 y un binding de plataforma restringido para TV; tampoco está implementado.

La revisión documental del 6 de octubre propone un mando activo por membresía/partida con controlGeneration, barrera de transferencia y operaciones consultables separadas del recibo inmutable. Cierra también la fuente de estímulo por ronda frente a vistas paralelas, el ingreso duradero antes de resolver, unidades de reloj, incidentes acotados sin reutilizar preguntas y autenticación web/nativa. Son diseños pendientes de esquemas/fixtures e implementación; leer el registro antes de programar esos flujos. Arquitectura y modelo ya distinguen la decisión Go del usuario de las propuestas técnicas todavía abiertas.

Después, el usuario exige modelos interoperables y errores con la misma estructura/información. Se añadió contracts/shared/schema.json como fuente neutral y generación TypeScript/Go/Dart para 22 modelos base. ErrorData distingue origen, causa, resultado incierto, mensaje traducible y recuperación; HTTP/mensajes/recibos usan ese mismo núcleo. Hay fixtures positivos/negativos y pruebas de serialización Go/Dart; los adaptadores de error del runtime y validadores completos de red siguen pendientes. La ficha pública del catálogo usa el tipo generado en Go y Svelte. No se construyó una app Flutter ni nuevos flujos de plataforma.

Se mostró una prueba aislada de PixiJS con tablero, cartas y dados fuera del repositorio, verificada en Chrome con WebGL; no acredita compatibilidad en TV ni adopción de la librería. Tras considerar Phaser 4 y Konva, el usuario pide comparar con Motion y su motor propio de vicen para animaciones sencillas. La recomendación actual es comprobar primero esa reutilización sobre DOM; Konva se evalúa si aparece una necesidad concreta de objetos/capas Canvas. La selección/integración sigue pendiente de decisión/pruebas; no integrar ahora dependencias gráficas. La revisión de AirConsole incorpora sus vías de TV/app/HDMI y distingue la duplicación en Chromecast antiguo de la app en modelos con Google TV. Para reacción se contempla la demora de la ruta de pantalla completa.

La aclaración posterior del usuario fija el alcance 2D con perspectiva y retira Three.js del perfil gráfico. Google documenta que el Web Receiver Cast no admite WebGL: mantener renderer sin WebGL para Cast directo, también en juegos 2D. Duplicación desde ordenador y app instalada en Google TV son vías distintas. El soporte real de TV/Chromecast sigue sin probarse; no se garantiza por marca/año o por usar Chromium.

La investigación confirma que Konva ofrece Canvas 2D, capas/grupos, imágenes, sprites por fotogramas y tweens sin exigir WebGL. La primera prueba propuesta debe medir bundle comprimido, primer dibujo, memoria, fluidez y reposo con tablero/cartas, sprite, perspectiva y cancelación/recuperación; desactivar escucha en el tablero público pasivo y detener animaciones al quedar estático u oculto. No se ha medido menor consumo frente a Phaser/PixiJS ni probado Konva en TV/Cast. Phaser conserva sus capacidades de motor completo como alternativa, con Canvas deprecado y funciones nuevas exclusivas de WebGL. El perfil conserva fuentes oficiales y pruebas requeridas; no se instaló Konva, PixiJS, GSAP o Phaser en el proyecto.

Se inspeccionó G:/dev/svelte/vicen/src/libs/motion y el motor relacionado de src/arts/motion, de solo lectura. El primero resuelve preferencias; EngineMotion contiene presets, WAAPI, spring, FLIP, cancelación/AbortSignal, finished y traspaso de velocidad, sobre HTMLElement. No incluye gestor dedicado de spritesheets, objetos Canvas o timeline general. arts/scene sí tiene un driver Canvas 2D, pero orientado a efectos ambientales/decorativos, no un árbol de objetos de tablero. Motion para JavaScript permite HTML/SVG, valores/objetos y secuencias; Konva añade dibujo y gestión de objetos Canvas. La reutilización requiere concretar exportaciones/aliases, puerto DOM, presets y adaptación explícita de SVG si procede. Se detectó que el spring integra 1/60 por callback de rAF sin tiempo transcurrido: corregir antes de usarlo con cadencias variables. No se modificó vicen, no se ejecutaron sus tests ni se probó el motor propio en TV/Cast; no copiar o portar por inferencia. El perfil gráfico recoge alcance y diferencias.

Última propuesta del usuario sobre Motion: añadir una función nueva para no interferir en la actual. Se recomienda springTimed(config: SpringConfig): MotionRun, conservando spring() y los presets actuales. Usaría timestamps, acumulador y pasos físicos constantes con trabajo acotado; conservaría handles, cancelación, movimiento reducido y traspaso de velocidad. La prueba de games2 evaluaría el nuevo driver, y cualquier migración posterior sería optativa. springTimed no está implementada, y el commit de esta sesión no modifica el repositorio vicen. Al retomar esta línea, verificar cadencias de 30/60/120 Hz, frames irregulares, interrupciones, cancelación e inversión; el coordinador visual sigue recuperando la proyección autoritativa de Go.

El usuario aclara expresamente que Phaser 4 es el motor actual y Phaser Editor 5 es el editor: la discrepancia está resuelta y no queda pendiente un enlace o respuesta sobre versiones. La comprobación del 6 de octubre en el archivo oficial y directamente en el registro npm devuelve phaser@latest = 4.2.1. El perfil gráfico incluye las fuentes. Esta aclaración no aprueba adoptar el motor/editor; la prioridad posterior de reducir peso y comparar la biblioteca propia orienta la siguiente evaluación a reutilizar el motor existente sobre DOM, con Konva condicionado a una necesidad concreta de Canvas.

Git y conservación del trabajo

El repositorio está en la rama main, con origin configurado para fetch/push a pippygames, creado por el usuario para este proyecto. El usuario autoriza commit y push de todo el trabajo de games2 al cerrar el 6 de octubre. El commit de cierre incluye documentación, modelos compartidos TypeScript/Go/Dart, localización del catálogo/API, el prototipo visual y este handoff. La base inicial es 0982ba0 (Initialize games2 foundation, 5 de octubre de 2026); no confundirla con la entrega de cierre. Consultar git log -1 --oneline, git status --short --branch y la correspondencia con origin/main al retomar. La demo aislada de PixiJS sigue fuera del repositorio en el directorio de visualizaciones de Codex, y vicen no se modificó.

Al abrir el proyecto nuevo, ejecutar git status --short en G:\dev\svelte\games2 y conservar cualquier cambio posterior al cierre. Una copia o worktree arrancada desde 0982ba0 no contendrá el trabajo de esta sesión; usar la entrega de cierre en main o un estado posterior verificado. No hacer reset --hard ni clean para preparar la continuación. El prototipo visual rechazado queda conservado en Git; su presencia no implica aprobación ni permiso para basar en él la interfaz final.

Verificación realizada el 6 de octubre

• npm run contracts:check en la raíz: pasa (5 manifiestos, 14 mensajes, 37 rechazos, 5 componentes, 52 huecos de arte, plan de presentación y 6 esquemas generados). Comprueba estructura de especificaciones v1, no ejecución de juegos Go ni el perfil multidispositivo v2.
• npm run check en frontend/: pasa, 0 errores y 0 advertencias.
• npm run build en frontend/: pasa.
• go test ./... en la raíz: pasa al fijar GOCACHE dentro del proyecto. El primer intento se detuvo antes de compilar porque la caché global de Windows no tenía permiso de lectura; no fue un fallo del código. En PowerShell:

$env:GOCACHE = 'G:\dev\svelte\games2\.cache\go-build'
go test ./...

No se ha hecho una prueba de carga, de PostgreSQL, de salas/partidas ni de producción. La compilación del frontend no aprueba el diseño visual.

En la revisión documental posterior se volvió a ejecutar contracts:check con resultado satisfactorio y se comprobaron 13 documentos, 170 referencias locales, 11 ejemplos JSON y coherencia de renderers. No se modificó runtime ni se repitieron las pruebas históricas de frontend/Go en esa revisión. El registro de revisión conserva alcance y límites.

Antes del commit de cierre se repitieron npm run contracts:check, go test ./..., npm run check y npm run build del frontend: todos pasan, con 0 errores/advertencias Svelte. También pasan los 14 round trips JSON Dart y dart analyze contracts/shared/dart usando directamente el SDK instalado. Se comprobaron 4 documentos de continuación, 63 enlaces locales y 2 bloques JSON sin incidencias. La comprobación Svelte y el build se ejecutaron fuera del sandbox porque Vite necesitaba escribir su caché temporal; no se cambió la configuración del proyecto para esta verificación. Estos resultados no acreditan los flujos pendientes, la estética del prototipo ni compatibilidad TV/Cast.

Siguiente trabajo recomendado

1. Abrir el directorio existente como proyecto nuevo y revisar git status, el commit de cierre, este handoff, README y ROADMAP. Conservar cualquier cambio nuevo antes de crear ramas o worktrees; la propuesta springTimed sigue pendiente si se retoma primero la prueba visual.
2. Empezar el primer corte vertical: PostgreSQL, migraciones, unidad de trabajo, repositorios, recibos y outbox duraderos; contratos ejecutables y pruebas de integración. Desde ese corte aplicar las invariantes de preparación para escalar.
3. Implementar un primer juego propio pequeño (Conecta 4) con motor Go, estado versionado, proyección por jugador, azar si procede y recuperación tras reinicio. Definir antes el perfil ejecutable Go del paquete, incluyendo soporte opcional de jugadores virtuales e instrucciones del agente en sus propiedades; los esquemas v1 TypeScript son referencia semántica, no código listo para Go. Probar el primer controlador junto con sus decisiones duraderas, privacidad y límites antes de habilitarlo.
4. Continuar protección, tiempo real, multidispositivo e idiomas por cortes del roadmap. Mantener desactivada cualquier capacidad no implementada en bootstrap. No prometer 100.000 jugadores hasta probar la topología real.

Si el objetivo de la próxima sesión cambia, estas decisiones y el estado de Git siguen siendo el punto de partida; el proyecto nuevo no necesita copiar archivos desde games v1.