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](game-engine/synchronization-profile.md) 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](platform/client-communication-profile.md) 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](game-engine/multi-device-profile.md#8-referencia-de-interacción-airconsole) 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](game-engine/multi-device-profile.md#televisores-y-dispositivos-externos) 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](game-engine/virtual-player-profile.md) 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](../README.md) |
| Orden de implementación | [ROADMAP](ROADMAP.md) |
| Entidades, salas, seguridad y operación | [Modelo de plataforma](platform-spec-v2.md) |
| Contratos HTTP y tiempo real | [API y eventos](platform/api-and-events.md) |
| Arquitectura Go de tres capas | [Arquitectura](platform/architecture.md) |
| Políticas de producto y menores | [Políticas](platform/product-policies.md) y [protección del menor](platform/child-safety.md) |
| Idiomas | [Localización](platform/localization.md) |
| Formato/protocolo v1 de juegos | [Formato y protocolo](game-engine/format-and-protocol.md), [propuesta del motor](game-engine-proposal.md) y esquemas/ejemplos de `docs/game-engine/` |
| TV y móvil como superficies del juego | [Perfil multidispositivo v2 propuesto](game-engine/multi-device-profile.md) |
| Reloj, rondas y equidad ante lag | [Perfil de sincronización v2 propuesto](game-engine/synchronization-profile.md) |
| Web y futura app Flutter; acciones y estado bidireccionales | [Perfil de comunicación de clientes v2](platform/client-communication-profile.md) |
| Modelos comunes Go/Svelte/Flutter y gestión de errores | [Modelos compartidos](platform/shared-data-models.md), fuente y bindings bajo `contracts/shared/` |
| Jugadores virtuales e instrucciones dentro del juego | [Perfil de agentes v2 propuesto](game-engine/virtual-player-profile.md) |
| Preparación para 100.000 jugadores | [Capacidad y escalado](platform/capacity-and-scaling.md) |
| Diseño visual aplazado | [Exploración no aprobada](platform/visual-design.md) |
| Evaluación y corrección de los documentos nuevos | [Revisión del 6 de octubre](platform/review-2026-10-06.md) |

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](game-engine/multi-device-profile.md#gráficos-y-requisitos-por-juego). 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](game-engine/multi-device-profile.md#gráficos-y-requisitos-por-juego) 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](game-engine/multi-device-profile.md#gráficos-y-requisitos-por-juego) 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](https://g.activething.com/go/pippygames.git), 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:

```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](platform/capacity-and-scaling.md#2-prepararla-desde-el-primer-juego-sin-pagar-el-clúster-ahora).
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.