Motor de Invitaciones

Documento tecnico que describe la arquitectura interna del motor de generacion de invitaciones HTML, el sistema de transiciones fullpage entre secciones, las pantallas de carga (loaders), el motor de particulas Canvas 2D y la integracion tematica que conecta todos estos subsistemas.

Tabla de Contenidos

1. Arquitectura del Motor
2. Secciones de Invitacion
3. Sistema de Transiciones Fullpage
4. Pantallas de Carga (Loaders)
5. Particulas Canvas 2D
6. Theme Color Bridge
7. Invitaciones Externas
8. Testing
9. Referencias

Arquitectura del Motor

El motor de invitaciones es el nucleo de generacion de HTML en Nvito. Su responsabilidad es tomar la configuracion de una invitacion (secciones, estilos, datos del evento, transiciones, loaders) y producir un documento HTML completo, autocontenido y listo para servir desde CDN. El resultado final se almacena en S3 (MinIO en desarrollo, Cloudflare R2 en produccion) como un conjunto de archivos HTML, CSS y JavaScript.

Flujo de Generacion HTML

Componentes del Motor

Almacenamiento en S3

El motor sube los archivos generados a un bucket S3 con la siguiente estructura:

invitations/
  {organizationId}/
    {invitationId}/
      index.html        # Documento HTML principal
      styles.css         # Estilos compilados del tema
      scripts.js         # JavaScript interactivo (RSVP, gallery, etc.)
      transitions.js     # Motor de transiciones (si aplica)
      loader.js          # Pantalla de carga (si aplica)

En desarrollo se utiliza MinIO como implementacion local compatible con S3. En produccion se utiliza Cloudflare R2, que ofrece compatibilidad con la API de S3 sin costos de egress.

Orden de Compilacion del TemplateCompiler

El TemplateCompilerService procesa el template en un orden estricto para evitar conflictos entre las distintas directivas:

1. resolveLoops — Expande {{#each items}}...{{/each}} iterando sobre arrays del contexto. Resuelve {{this.campo}} dentro del loop.
2. resolveConditionals — Evalua {{#if condicion}}...{{/if}} y {{#unless condicion}}...{{/unless}}. Remueve bloques no aplicables.
3. resolveIcons — Reemplaza {{icon:nombre}} por el SVG correspondiente del catalogo de iconos.
4. resolveVariables — Sustituye {{variable}} por el valor del contexto de datos del evento.

Este orden es critico: los loops deben resolverse primero porque pueden contener iconos anidados (por ejemplo {{icon:{{this.icon}}}} dentro de un {{#each}}). El loop resuelve {{this.icon}} a un nombre concreto, dejando {{icon:calendar}} que el paso de iconos procesa correctamente.

Secciones de Invitacion

Cada invitacion esta compuesta por multiples secciones, donde cada seccion representa un bloque visual con un tipo especifico, configuracion JSON y un orden de aparicion. Las secciones son la unidad fundamental de composicion del motor.

Tipos de Seccion

Modelo de Datos

Cada seccion se almacena en la tabla InvitationSection con los siguientes campos principales:

Restricciones

• El numero maximo de secciones depende del plan contratado por la organizacion.
• Solo las secciones con visible: true se incluyen en el HTML generado.
• La seccion Hero siempre debe ser la primera (order = 0) y no puede ocultarse.
• Las secciones se renderizan como paginas fullpage, donde cada seccion ocupa el 100% del viewport y se navega entre ellas con scroll o transiciones.

Sistema de Transiciones Fullpage

El sistema de transiciones controla como se anima el cambio entre secciones cuando el usuario navega la invitacion. Nvito ofrece 27 transiciones divididas en dos categorias: clasicas (CSS puro) y cinematograficas (Canvas 2D con motor de 3 fases).

Catalogo de Transiciones

Transiciones Clasicas (10) — CSS Only

Transiciones Cinematograficas (17) — Canvas 2D + 3 Fases

Motor de 3 Fases

Las transiciones cinematograficas siguen un ciclo de 3 fases ejecutado por el TransitionEngine:

Detalle de las Fases

Fase CLOSE (IN: 0.9s) El overlay comienza a cubrir el viewport. Si la transicion tiene Canvas, el efecto visual se inicia simultaneamente sobre el overlay. El usuario ya no puede interactuar con la seccion actual. El Canvas se inicializa con requestAnimationFrame para renderizar el efecto a 60fps.

Fase STAMP (1.0s total) Una vez que el viewport esta completamente cubierto, aparece el monograma del evento (iniciales de los anfitriones) con una animacion de entrada (0.7s). Debajo del monograma se muestra el nombre de la seccion destino. El monograma se mantiene visible brevemente y luego sale con una animacion de desvanecimiento (0.6s).

Fase OPEN (OUT: 0.85s) El overlay sale de escena revelando la seccion destino ya posicionada debajo. El Canvas se detiene y se limpia (cancelAnimationFrame + clear del contexto). Los event listeners temporales se remueven.

Timing Comparativo

Modelo TransitionStyleDefinition

Cada transicion se define como un objeto TransitionStyleDefinition con los siguientes campos:

Pantallas de Carga (Loaders)

Las pantallas de carga se muestran mientras la invitacion carga sus recursos (imagenes, fuentes, scripts). El loader debe dar una experiencia visual atractiva que mantenga la atencion del usuario durante los segundos iniciales.

Catalogo de Loaders

CSS Clasicos (8)

Canvas 2D Cinematograficos (17)

Generacion de Loaders

La funcion generateLoaderJs recibe un objeto LoaderStyleDefinition completo (no solo la duracion) y produce el codigo JavaScript que inicializa el loader. Para loaders Canvas, el codigo generado incluye:

1. Inicializacion del Canvas — Crea el elemento <canvas>, lo dimensiona al viewport y obtiene el contexto 2D.
2. Loop de animacion — Usa requestAnimationFrame para renderizar particulas o efectos a 60fps.
3. Barra de progreso — Superpuesta al efecto, muestra el porcentaje de carga real.
4. Cleanup — Al completar la carga, detiene el loop, remueve el canvas y ejecuta la animacion de salida.

Modelo LoaderStyleDefinition

Responsividad y Accesibilidad

Los loaders Canvas implementan dos mecanismos de fallback para garantizar una buena experiencia en todos los dispositivos:

Mobile fallback: En pantallas menores a 640px de ancho, el Canvas se oculta y solo se muestra la version CSS del loader. Esto evita problemas de rendimiento en dispositivos moviles con GPUs limitadas y reduce el consumo de bateria.

Reduced motion: Cuando el usuario tiene activada la preferencia prefers-reduced-motion: reduce en su sistema operativo, el Canvas se oculta completamente. La barra de progreso y el texto del loader se mantienen visibles pero sin animaciones, respetando la preferencia de accesibilidad del usuario.

Particulas Canvas 2D

El motor de particulas es un subsistema compartido por transiciones y loaders que proporciona 26 tipos de particulas con fisica, ciclo de vida y funciones de dibujo independientes. Cada tipo de particula esta disenado para representar un elemento visual especifico con comportamiento fisico realista.

Arquitectura del Motor de Particulas

Cada tipo de particula se define como un objeto con tres responsabilidades:

1. init() — Inicializa la particula con posicion, velocidad, tamano, color y propiedades especificas del tipo (rotacion, opacidad, forma).
2. update(dt) — Actualiza la fisica de la particula en cada frame: gravedad, resistencia del aire, rotacion, desvanecimiento. Recibe dt (delta time) para animacion independiente del framerate.
3. draw(ctx) — Dibuja la particula en el contexto Canvas 2D usando las primitivas apropiadas (arcos, paths, bezier curves, imagenes).

Catalogo de 26 Tipos de Particulas

Ciclo de Vida de una Particula

Cuando una particula "muere" (opacidad llega a 0 o sale completamente del viewport), se marca como inactiva y se remueve del array de particulas activas. El motor puede opcionalmente reciclar particulas muertas (respawn) si la transicion o loader lo requiere para mantener una densidad visual constante.

Theme Color Bridge

El Theme Color Bridge es el subsistema que conecta los colores del tema de la invitacion con los efectos Canvas 2D. Su proposito es que las transiciones y loaders cinematograficos se integren visualmente con el esquema de colores elegido por el usuario, manteniendo coherencia estetica sin sacrificar la identidad visual de particulas naturales.

Arquitectura

Funcionamiento

El archivo utils/theme-color-bridge.ts se ejecuta al iniciar la invitacion y realiza las siguientes operaciones:

1. Lectura de CSS variables — Lee las variables CSS del tema (--t-overlay, --t-accent, --t-accent-light, --t-background, --t-primary) del elemento root del documento.
2. Conversion a RGB arrays — Convierte cada color hexadecimal o HSL a un array [R, G, B] (valores 0-255) para uso directo en el Canvas 2D.
3. Exposicion global — Almacena los colores en window.__tc (theme colors) como un objeto con propiedades: overlay, accent, accentLight, background, primary. Cada propiedad es un array [number, number, number].

El bridge se inyecta en dos puntos:

• loader-base.js.ts — Para que los Canvas loaders accedan a __tc durante su inicializacion.
• transition-engine.ts — Para que las Canvas transiciones accedan a __tc al crear particulas.

Principio de Diseno: Paleta Derivada con Identidad Preservada

El bridge sigue un principio de diseno fundamental: las particulas que representan elementos naturales reconocibles mantienen sus colores reales, mientras que los elementos artificiales o abstractos adoptan la paleta del tema.

La razon es cognitiva: un petalo rosa, una hoja verde o una luciernaga amarilla son reconocibles por su color natural. Cambiar esos colores para "encajar" con el tema romperia la ilusion y haria que las particulas se vean genericas. En cambio, el confeti, las formas geometricas, las ondas neon o los destellos no tienen un color "correcto" inherente, por lo que se benefician de adoptar la paleta del tema para crear una experiencia visualmente integrada.

Clasificacion de Canvas Loaders

9 loaders tematicos (usan __tc del tema):

8 loaders con colores naturales fijos (NO usan __tc):

Clasificacion de Canvas Transiciones

4 transiciones tematicas (usan __tc):

• shimmer-veil — Destellos abstractos, color adaptable
• neon-grid — Rejilla neon, color definido por el tema
• firework-bloom — Fuegos artificiales, multicolor adaptable
• confetti-burst — Explosion de confeti, inherentemente tematico

10 transiciones con colores naturales fijos (NO usan __tc):

• petal-drift — Petalos: rosa y blanco
• leaf-cascade — Hojas: verdes y marrones
• butterfly-waltz — Mariposas: colores de alas naturales
• feather-fall — Plumas: blancas y crema
• bubble-rise — Burbujas: translucidas con reflejo azulado
• rose-bloom — Rosa: rojo y rosa
• sacred-glow — Luz sagrada: dorado y blanco
• celestial-veil — Estrellas: blanco y plateado
• golden-sweep — Destellos dorados: siempre dorado
• aurora-wave — Aurora: verde-azul-violeta natural

Integracion con CSS

Ademas del bridge para Canvas, los componentes CSS de transiciones y loaders utilizan variables CSS directamente con fallbacks:

/* Ejemplo de transicion CSS tematizada */
.overlay-background {
  background-color: var(--t-overlay, #0a0a0a);
}

.accent-glow {
  color: var(--t-accent, #d4af37);
  box-shadow: 0 0 20px var(--t-accent-light, rgba(212, 175, 55, 0.3));
}

/* Barra de progreso tematizada en todos los loaders */
.progress-bar {
  background-color: var(--t-accent, #d4af37);
}

Esto garantiza que incluso si el JavaScript del bridge no se ejecuta (por ejemplo, con JavaScript deshabilitado), los estilos CSS tienen fallbacks razonables que mantienen la coherencia visual.

Invitaciones Externas

Las invitaciones externas permiten a los usuarios subir HTML disenado fuera de Nvito y publicarlo a traves de la misma infraestructura de entrega (CDN, analiticas, RSVP). El motor diferencia entre invitaciones internas y externas a traves del enum InvitationSource.

Enum InvitationSource

HtmlValidatorService

El HtmlValidatorService ejecuta 9 pasos de validacion sobre el HTML externo antes de permitir su almacenamiento:

Flujo de Upload

Comportamiento Condicional en Publicacion

Cuando una invitacion externa se aprueba y publica, el flujo de publicacion tiene una diferencia clave respecto a las invitaciones internas:

• INTERNAL: El DocumentGeneratorService genera el HTML completo a partir de las secciones, lo compila, le inyecta transiciones/loaders/analiticas, y lo sube a S3.
• EXTERNAL: El motor omite la generacion HTML (ya existe en S3). Solo inyecta el snippet de analiticas en el HTML existente para tracking de visitas y RSVP.

Otros comportamientos condicionales:

• Edicion de secciones: Bloqueada para invitaciones externas (no tienen secciones editables).
• Versionamiento: Deshabilitado (siempre version 1). Para actualizar, el usuario hace re-upload del HTML completo.
• Transiciones y loaders: No aplican (el HTML externo maneja su propia navegacion).
• IA conversacional: No disponible para invitaciones externas.

Testing

El motor de invitaciones cuenta con una cobertura de tests exhaustiva que cubre transiciones, loaders, integracion tematica, el validador HTML y el compilador de templates.

Resumen de Tests

Que se Prueba

Transiciones:

• Cada transicion genera CSS/JS valido
• Las fases CLOSE/STAMP/OPEN respetan el timing configurado
• Canvas init y cleanup se ejecutan correctamente
• El monograma y el label de seccion se renderizan
• Los 14 tipos de evento de Nvito tienen al menos una transicion sugerida

Loaders:

• Cada loader genera HTML/CSS/JS valido
• La barra de progreso refleja el porcentaje de carga
• Mobile fallback oculta Canvas en pantallas menores a 640px
• Reduced motion oculta Canvas con prefers-reduced-motion
• generateLoaderJs recibe LoaderStyleDefinition completo

Integracion tematica:

• El bridge lee correctamente las CSS variables --t-*
• Los 9 loaders tematicos usan __tc para sus colores
• Los 8 loaders naturales NO usan __tc (colores fijos verificados)
• Las 4 transiciones tematicas usan __tc
• Las 10 transiciones naturales NO usan __tc
• Los 14 tipos de evento tienen cobertura tematica

HtmlValidatorService:

• 37 tests cubriendo los 9 pasos de validacion
• Vectores de ataque XSS reales
• HTML malformado, encoding incorrecto, tamano excesivo

Referencias

Motor de Generacion

• DocumentGeneratorService: src/modules/invitations/services/document-generator.service.ts
• TemplateCompilerService: src/modules/invitations/services/template-compiler.service.ts
• HtmlGenerationModule: src/modules/invitations/html-generation/

Transiciones

• TransitionEngine: src/modules/invitations/transitions/transition-engine.ts
• Definiciones de transiciones: src/modules/invitations/transitions/definitions/
• Tests: src/modules/invitations/transitions/__tests__/

Loaders

• LoaderGenerator: src/modules/invitations/loaders/loader-generator.ts
• Definiciones de loaders: src/modules/invitations/loaders/definitions/
• Tests: src/modules/invitations/loaders/__tests__/

Particulas

• ParticleGenerator: src/modules/invitations/particles/
• 26 tipos: src/modules/invitations/particles/types/

Theme Bridge

• theme-color-bridge.ts: src/modules/invitations/utils/theme-color-bridge.ts

Invitaciones Externas

• HtmlValidatorService: src/modules/invitations/services/html-validator.service.ts
• ExternalInvitationService: src/modules/invitations/services/external-invitation.service.ts
• ExternalInvitationController: src/modules/invitations/controllers/external-invitation.controller.ts

Documentacion Relacionada

• Sistema de Invitaciones — Maquina de estados, flujos de creacion, versionamiento
• Notificaciones y Comunicaciones — Envio de campanas relacionadas con invitaciones
• Invitaciones Publicas — Renderizado de invitaciones en nvito-invitations