SAGA Engine v2.1.0

Esta actualización se centra en perfeccionar la interfaz de administración para dispositivos iOS modernos y continúa mejorando las herramientas de creación de contenido para ofrecer un entorno de trabajo impecable.

📱 Compatibilidad y Ajustes de Interfaz en iOS

Notch Layout y Dynamic Island: Corrección integral de los márgenes dinámicos en el panel de administración para evitar solapamientos e interferencias con la Dynamic Island de los iPhone.

Safe Areas (Barra Superior y Left Rail): Ajuste milimétrico de la navegación superior y el panel lateral izquierdo. Todos los elementos interactivos ahora respetan las áreas seguras de la pantalla, garantizando un acceso táctil preciso y sin recortes visuales desde cualquier dispositivo móvil.

🛠️ Evolución del Editor Guiado

Rediseño Visual: Actualización estética y estructural del editor guiado de nodos. Se ha refinado la interfaz para hacer el flujo de diseño de misiones aún más limpio, intuitivo y libre de distracciones visuales.

⚡ Rendimiento y Estabilidad

Optimizaciones Core: Continuidad en el soporte y fluidez de la plataforma bajo el entorno de producción en contenedores Docker (arquitectura ARM64), asegurando tiempos de carga mínimos en el panel de administración rediseñado.

SAGA Engine v2.0.0

🎒 v2.0.0 - Rediseño UI Mochila, Editor Guiado y Estabilidad

La versión 2.0.0 consolida de manera oficial el estado operativo real y optimizado directamente desde el entorno de producción en la Raspberry Pi. Esta actualización refina la experiencia de juego táctil y asegura la usabilidad del panel de administración.

🎒 Rediseño de la App del Jugador

• Mochila Renovada: Lavado de cara integral al panel de inventario, sustituyendo iconos antiguos por versiones modernas, estilizadas y legibles en pantallas móviles.
• Mesa de Trabajo Premium: Flujo visual simplificado y optimizado para el sistema de combinación de ingredientes (crafting) en tiempo real.

🛠️ Editor Guiado y Creador de Nodos

• Flujos Paso a Paso: Transformación completa de los menús de diseño de misiones en el panel de administración. Ahora guían al usuario de forma gráfica y secuencial, reduciendo la redundancia de textos liosos.

⚡ Corrección de Errores y Hardening Core

• Fix Crítico de Coleccionables: Reparación definitiva del bug en el editor guiado que omitía la asignación interna del tipo correcto (signal_hunt) a los nodos de tipo "Coleccionable en mapa". Ahora se guardan al instante, mostrando correctamente el marcador verde con estrella (⭐) en la lista y la previsualización interactiva del mapa.
• Rendimiento ARM64: Optimización interna de tiempos de respuesta y velocidad de transiciones bajo entornos Docker.

SAGA Engine v1.4.0

👥 v1.4.0 - Multijugador, Crafting y GPS Tracker

Esta actualización transforma SAGA Engine de una experiencia individual a una plataforma totalmente cooperativa y añade mecánicas avanzadas de gestión de inventario.

🚀 Novedades Principales

• Sistema Multijugador: Implementación de la gestión de equipos y sincronización cooperativa de progreso y eventos en tiempo real.
• GPS Tracker en Vivo: Las coordenadas de posición de los compañeros de equipo ahora se dibujan dinámicamente como marcadores de color sobre el mapa del jugador.
• Mesa de Trabajo Avanzada: Introducción del sistema de combinación de objetos (crafting) dentro del panel de herramientas, permitiendo fusionar ítems recolectados para superar etapas.
• Inventory Grid UI: Nueva cuadrícula interactiva para la mochila que mejora sustancialmente la inspección de recompensas y herramientas.

SAGA Engine v1.3.0

🛰️ v1.3.0 - Offline GPS & Map Render Fixes

🐛 Correcciones

• Caché Regional Agresiva: Incremento masivo del radio de precarga offline.
• Ruta de Contingencia Offline: Línea de vuelo de pájaro al perder OSRM.

SAGA Engine v1.2.0

🌍 v1.2.0 - Mapbox Premium e Internacionalización

Un salto de calidad visual y funcional.

✨ Nuevas Características

• Mapbox Premium: Soporte integrado para mapas Mapbox.
• Rediseño UI (Fase 1): Actualización de tarjetas y HUD.
• i18n: Sistema bilingüe Inglés/Español dinámico.

SAGA Engine v1.1.0

Rediseño de interfaz, correcciones GPS y rendimiento de mapa, y Desafío de Audio

SAGA Engine v1.0.1

SAGA Engine v0.5.4 — Tools and QR Studio release

SAGA Engine v0.5.4 improves the field experience without adding another game.
It consolidates offline preparation into a compact Tools panel and adds a safe,
validated QR card workflow to Mission Control.

Compact field Tools

• Aligns Tools with the established SAGA player design.
• Removes duplicated headings and explanatory copy.
• Uses one action to prepare mission data, map tiles, games and field photographs for offline play.
• Keeps photograph downloads for the device gallery as a separate action.
• Preserves progress save, synchronization, GPS centring, language, fallback code and diagnostics.
• Leaves the bottom navigation and mobile safe areas unchanged.

QR Studio

• Adds clear, dark and photographic card presets.
• Supports configurable accent colour and square or rounded cards.
• Optimizes uploaded header photographs without placing them over QR modules.
• Keeps QR codes on a white, high-contrast surface with error-correction level H.
• Adds camera validation using exact payload comparison.
• Blocks PNG export until the current payload and design have been validated.
• Invalidates the previous validation after any payload, photograph, colour, shape or preset change.
• Does not modify inventory, node completion or player progress during validation.

Offline preparation

The preparation action now caches the player shell, mission configuration, map
tiles and field-proof assets together. Successful preparation remains compatible
with later progress saving and pending-event synchronization.

Validation

• Dedicated Tools and QR Studio guard.
• Offline/GPS hardening and recovery guards.
• Marker, routing, privacy and protected-files guards.
• Runtime contracts inside Docker.
• TypeScript and Vite production build.
• npm audit with zero known vulnerabilities.
• Candidate-first Docker deployment and smoke checks for /, /admin-react and /player/PLAYER%201.

Follow-up work

• Test QR scanning across more phones, cameras, screens, printers and lighting conditions.
• Consider PDF/A4 batch export after the single-card workflow is proven.
• Continue reducing the frontend bundle through game-level dynamic imports.

SAGA Engine v1.0.0 — First stable release

Changelog

All notable changes to SAGA Engine are documented in this file.

---

[1.0.0] — 2026-06-23

🎉 First stable release

This release marks the transition from the feature development phase (v0.5.x) to a stable, field-tested platform. Virtually every layer of the stack was touched: new offline architecture, a complete minigame runtime system, an overhauled player UI, GPS hardening, field photo proofs with ZIP export, a redesigned login flow, a professional deploy pipeline, and much more.

---

✨ New features

Player experience

• New PlayerHud bar — completely redesigned bottom HUD with glassmorphism style, matching the login palette and top bar. Clean separation of primary action, details, tools and GPS state.
• New PlayerShell bar — redesigned top bar with player avatar, mission progress, GPS indicator and team access.
• Backpack (Mochila) panel — inventory panel listing all collected items, next-node preview with game type description, and field context.
• Tools panel — redesigned with: field photo download as ZIP, QR quick-scan launcher, field camera, offline sync, and an in-app field assistant guide.
• In-app assistant guide — explains how to play each minigame family and how to use core tools (QR scan, GPS, mochila), accessible from the Tools panel.
• Field Photo Proofs (ZIP export) — players can download all their geolocated field photos as a single ZIP file directly from the Tools panel.
• QR distance error toast — scanning a QR node while out of range now shows a centered, auto-dismissing toast (3 seconds) below the player bars instead of a generic alert.
• Route overview map control — quick-controls bar on the map now includes a route toggle button to see all nodes at once.
• Team presence on map — real-time team member positions drawn as colored markers on the player map.
• Celebration overlay — brief animated overlay on node clear and mission finish.
• Mission finish screen — full finish screen with stats (nodes cleared, photos taken), accessible again via a floating trophy button.

Login

• GPS permission request at login — the login now asks for GPS permission before entering the player. If denied, the user enters without location and can use debug simulation.
• No transition animation — removed the "Entrando como…" loading overlay between login and player for a seamless experience.
• Offline vault summary — login shows each player's offline preparation state.

Offline & PWA

• Mission Pack offline download — players can download the full mission (payload, config, team profiles, field proofs, map tiles) from the Tools > Offline Prep panel before going to the field.
• Map tile prefetch — before going offline, the system prefetches all OSM tile URLs needed to cover the mission route.
• Offline GPS storage — last known GPS position is stored locally so the map can center correctly on first load even without a fresh fix.
• Offline field proof cache — field photos are cached locally and synced when connectivity returns.
• Offline team presence — team positions are cached and shown on the map even offline.
• Service Worker hardening — improved SW registration, unregister helper, and cache strategy for offline-first operation.
• Local-first advance — node submission falls back to local offline progression when the server is unreachable, queuing the event for sync.

Minigames

• Minigame runtime system — complete generic runtime architecture (FamilyRuntimeHost, registry, resolver, runtime-bridge) enabling any game family to run inside the player without coupling to PlayerApp.
• Circuit Matrix — connect circuit paths on a configurable grid to light up nodes. Visual circuit path editor in admin.
• Sequence Code — decode and replicate sequences. Admin editor with drag-and-drop sequence builder.
• Bearing Hunt — navigate by compass bearing toward a target. Definition with configurable tolerance.
• Signal Hunt — locate an oscillating signal source. Definition with configurable frequency and range.
• Motion Challenge — physical movement reto using device motion events. Admin editor with challenge config.
• Place Mosaic — reconstruct a fragmented image of a physical place. Admin editor.
• Tilt Maze — accelerometer-controlled maze. Shared tiltMaze physics module. Admin editor.

Admin panel

• Game Template Wizard — step-by-step wizard to create a new mission from a template, with game family selection.
• Families panel — browse and configure all available game families from a single panel.
• QR Studio v2 — redesigned QR card generation studio with print-ready layouts, multiple formats, and batch generation.
• Guided Node Editor Flow — guided multi-step node creation flow: location → game type → physical QR → publish.
• Physical node types — full support for collectible, requirement, clue, and bonus node kinds, with visual indicators on the admin map.
• Node physical type panel — dedicated panel to configure physical QR parameters per node.
• Requirement preview panel — players can preview required items before activating a node.
• Admin mission map — improved map in admin with real-time player positions, node states, and field proof markers.
• i18n / locale — admin interface locale toggle (ES/EN) with full Spanish bridge for legacy strings.
• Players panel — create, edit and manage player profiles and team compositions.
• Settings panel — all mission-wide configuration in one place (site name, story, GPS radius, offline settings, etc.).

Deploy pipeline

• deploy_saga_safe.sh — zero-downtime blue/green deploy script:
  • Builds new Docker image
  • Starts candidate on alternate port (18096)
  • Runs smoke tests against candidate
  • Promotes to production (8096) only if all smokes pass
  • Cleans up candidate container
• Version + build time injection — SAGA_VERSION and SAGA_BUILD_TIME are injected at deploy time and shown in the BuildInfoBadge in the player UI.
• Local timezone build time — build time is captured in local timezone (CEST) instead of UTC to avoid confusion.

---

🔧 Improvements

• PlayerApp refactor — extracted layout primitives (ScreenFrame, getViewportStyle, CelebrationOverlay, getTopOverlayStyle, getBottomOverlayStyle, getMapQuickControlsStyle, finishOverlayStyle, etc.) into a dedicated PlayerLayout.tsx component, reducing PlayerApp.tsx from ~2300 lines.
• GPS accuracy feedback — GPS status now shows accuracy in meters when below threshold, with a separate "imprecise GPS" warning in the HUD helper text.
• GPS staleness detection — positions older than 15 seconds are marked "stale" and don't unlock nodes.
• Distance display — distance to active node shown in HUD with color-coded feedback (far / approaching / in range).
• Map quick controls floating bar — camera, team, route and QR buttons grouped in a pill-shaped glassmorphism bar centered above the HUD.
• Toast notice system — unified ToastNotice component for info/warning toasts with 3-second auto-dismiss.
• BuildInfoBadge — version + build time badge visible in login and player UI.
• ErrorBoundary — global React error boundary to prevent full crashes from rendering errors.
• Collectible rewards rules — collectibleRules.ts engine for evaluating unlock conditions on collected items.
• Manual inventory collect panel — UI for manually collecting physical inventory items.
• OfflineSyncPanel — status panel showing pending offline events and sync state.
• Field prep panel — pre-field preparation checklist with offline download controls.
• Map surface CSS — dedicated map-surface.css for Leaflet overrides and node marker styles.
• GPS storage utilities — gpsStorage.ts for persisting and reading the last GPS fix across sessions.
• Stage position utilities — stagePosition.ts for deriving active stage lat/lon/radius from payload.
• Player identity — playerIdentity.ts for avatar URL, initials and color derivation.
• Player route — playerRoute.ts for extracting player name from URL path.
• Offline public config — offlinePublicConfig.ts for caching and reading the public configuration offline.
• Offline vault — offlineVault.ts for persisting a cross-player offline readiness summary.

---

🐛 Bug fixes

• Fixed: field photo download produced a .txt file instead of .zip — corrected by using JSZip with proper MIME type and Blob construction.
• Fixed: duplicate handleDownloadFieldProofs function caused TypeScript compilation failure.
• Fixed: TypeScript import conflict between local declarations and imports from PlayerLayout (getBottomOverlayStyle, getToastOverlayStyle, OverlayState).
• Fixed: orphan closing </div> after removing the inner viewport wrapper caused JSX parse error and broken HUD layout.
• Fixed: ScreenFrame double-wrapper bug — PlayerApp was wrapping children in both ScreenFrame (which already applied getViewportStyle) and an additional <div style={getViewportStyle()}>, breaking the absolute positioning of both top and bottom HUD bars.
• Fixed: login to player transition showed a "Preparando jugador" loading card — removed in favor of an instant dark background.
• Fixed: second "Entrando como…" animation was playing on player load from the StatusCard component.
• Fixed: OverlayState type mismatch between PlayerLayout export and internal uses ('activate' | 'node' | 'finish' vs 'success' | 'finish' | 'error').
• Fixed: deploy script had Windows line endings (\r\n) causing bash set -euo pipefail\r error on Linux.

---

🗑️ Removed

• Removed "Preparando jugador" StatusCard from the idle/loading state — replaced with a plain dark background.
• Removed "Entrando como…" StatusCard overlay that appeared during login→player transition.
• Removed `launc...