2.3.3 (Nov 26, 2025)

⚙️ LolTimeFlash v2.3.3 - Components Architecture Refactor

🔄 Overview

This release refactors the game components architecture by organizing them into logical folders and migrating all relative imports to TypeScript path aliases for better maintainability and consistency.

♻️ Refactoring

• Components Organization: Reorganized game components into logical folders (game/, room/, status/, controls/)
• Path Aliases Migration: Replaced all relative imports (../) with TypeScript path aliases (@/features/game/...)
• Simplified Structure: Removed unnecessary ui/ and input/ folders, moving components directly to components/

📝 Documentation

• Updated VERSIONS.md with new version entry
• Updated AGENTS.md footer with current version

📦 Technical Changes

Frontend:

• New Structure:

  • components/game/ - Game-specific components (role-card, flash-button, timer-controls, etc.)
  • components/room/ - Room/lobby components (room-info, user-list, mobile-user-list, etc.)
  • components/status/ - Status components (connection-status, game-info-display)
  • components/controls/ - Control components (game-controls)
  • components/ - Direct components (loading-spinner, summoner-input)

• Import Migration:

  • All imports now use @/features/game/... instead of relative paths
  • Improved IDE autocomplete and refactoring support
  • Better consistency across the codebase

Modified Files:

File	Changes
apps/web/features/game/components/game/*	Moved from root, updated imports
apps/web/features/game/components/room/*	Moved from root, updated imports
apps/web/features/game/components/status/*	Moved from root, updated imports
apps/web/features/game/components/controls/*	Moved from root, updated imports
apps/web/features/game/components/*.tsx	Updated imports to use aliases
apps/web/features/game/screens/*.tsx	Updated imports to use aliases
apps/web/features/game/contexts/*.tsx	Updated imports to use aliases
apps/web/features/game/hooks/*.ts	Updated imports to use aliases
apps/web/features/game/constants/*.ts	Updated imports to use aliases

🎯 Impact

• Developers: Easier navigation and refactoring with consistent import paths
• Maintainability: Better code organization reduces cognitive load
• IDE Support: Improved autocomplete and type checking with path aliases

---

Full Changelog: https://github.com/yourusername/LolTimeFlash/compare/v2.3.2...v2.3.3

2.3.2 (Nov 24, 2025)

✨ LolTimeFlash v2.3.2 - Username Validation & Lobby Refactor

🔄 Overview

This release adds robust username validation (3-12 characters) with visual feedback and refactors the lobby page into clean, atomic components following proper architecture patterns.

✨ What's New

• Username Length Validation: Enforced 3-12 character limit on backend (DTO) and frontend
• Visual Validation Feedback: Real-time check/cross indicators for username requirements
• Lobby Architecture Refactor: Complete rewrite with atomic, memoized components
• Better UX: Dynamic color feedback (green for valid, red for invalid)

📝 Documentation

• Updated component architecture documentation
• Added username validation guidelines

📦 Technical Changes

Backend:

• New constants: MIN_USERNAME_LENGTH = 3, MAX_USERNAME_LENGTH = 12 in apps/api/libs/shared/src/constants/username.ts
• Updated JoinRoomDto validation to use constants (local copy to avoid decorator issues)
• Server-side validation prevents malicious localStorage manipulation

Frontend:

• New component: UsernameValidationFeedback.component.tsx (memoized, reusable)
  • Real-time visual feedback with check/cross icons
  • Dynamic color changes (gray/green/red)
  • Conditional visibility (invisible until user types)
• Refactored: apps/web/app/lobby/page.tsx (134 → 28 lines, -78%)
  • New components: CreateLobbyForm, JoinLobbyForm, LobbyDivider
  • All components memoized for performance
  • Followed features/ architecture pattern
  • Barrel exports with index.ts
• Updated: username-input-modal.component.tsx and settings/page.tsx
  • Integrated UsernameValidationFeedback component
  • Removed maxLength attribute to allow validation detection

Architecture:

• New feature module: features/lobby/components/
• Kebab-case naming convention enforced
• Component memoization with React.memo()
• Props interfaces with I prefix

Modified Files:

File	Changes
apps/api/libs/shared/src/constants/username.ts	Created - Username length constants
apps/api/src/game/dto/join-room.dto.ts	Updated validation (3-12 characters)
apps/web/features/settings/components/username-validation-feedback.component.tsx	Created - Validation feedback component
apps/web/features/settings/components/username-input-modal.component.tsx	Integrated validation feedback
apps/web/app/settings/page.tsx	Integrated validation feedback
apps/web/features/lobby/components/create-lobby-form.component.tsx	Created - Atomic component
apps/web/features/lobby/components/join-lobby-form.component.tsx	Created - Atomic component
apps/web/features/lobby/components/lobby-divider.component.tsx	Created - Atomic component
apps/web/features/lobby/components/index.ts	Created - Barrel exports
apps/web/app/lobby/page.tsx	Refactored - 78% code reduction

🎯 Impact

✅ Backend prevents username manipulation attempts (localStorage bypass)
✅ Users get instant visual feedback on username validity
✅ Lobby page now follows best architecture practices
✅ Performance improved with component memoization
✅ Codebase more maintainable with atomic components

---

Full Changelog: https://github.com/yourusername/LolTimeFlash/compare/v2.3.1...v2.3.2

2.3.1 (Nov 24, 2025)

⚙️ LolTimeFlash v2.3.1 - Username Storage Refactor

🔄 Overview

This patch release simplifies username storage by removing an unnecessary Zustand store and migrating to direct localStorage access, reducing boilerplate code and improving performance.

♻️ Refactoring & Optimization

• Username Storage Simplification: Removed username.store.ts (Zustand) in favor of direct localStorage usage
• useState Optimization: Initialize useState directly from localStorage instead of using redundant useEffect hooks
• Architecture Cleanup: Simplified 3 components (username-provider, settings/page, game/[roomId]/page)

📝 Documentation

• VERSIONS.md: Created dedicated file for version history
• AGENTS.md: Cleaned up (removed "Known Issues", moved version history, added MR guidelines)

📦 Technical Changes

Frontend:

• Removed apps/web/app/store/username.store.ts (replaced by localStorage)
• Refactored apps/web/components/providers/username-provider.component.tsx (Zustand → useState + localStorage)
• Refactored apps/web/features/settings/components/username-input-modal.component.tsx (Zustand → localStorage direct)
• Optimized apps/web/app/settings/page.tsx (useEffect → useState init)
• Optimized apps/web/app/game/[roomId]/page.tsx (Zustand → useState + localStorage)

Documentation:

• Updated AGENTS.md (cleanup + MR guidelines)
• Created VERSIONS.md (version history centralization)

Modified Files:

File	Changes
apps/web/app/store/username.store.ts	Deleted (replaced by localStorage)
apps/web/components/providers/username-provider.component.tsx	Zustand → useState + localStorage
apps/web/features/settings/components/username-input-modal.component.tsx	Zustand → localStorage direct
apps/web/app/settings/page.tsx	useEffect → useState init
apps/web/app/game/[roomId]/page.tsx	Zustand → useState + localStorage
AGENTS.md	Cleanup + MR guidelines
VERSIONS.md	Created - Version history

🎯 Impact

• ✅ ~40 lines of code reduction (store + useEffect removal)
• ✅ Slightly improved performance (fewer re-renders)
• ✅ Cleaner and more maintainable codebase
• ✅ Simpler state management pattern for single values

---

Full Changelog: https://github.com/yourusername/LolTimeFlash/compare/v2.3.0...v2.3.1

2.3.0 (Nov 24, 2025)

✨ LolTimeFlash v2.3.0 - Timer Calibration Controls & UX Polish

🔄 Overview

This release introduces timer calibration controls and major UX enhancements to the timer system, along with visual improvements using League of Legends champion ability icons.

✨ What's New

• Timer Calibration Controls: Added +2s/-2s buttons to recalibrate timers in real-time
• Fake Advance: Timers now start at X:57 (3s advance) to simulate reaction delay
• Zilean Abilities Icons: Using Zilean's W/E ability icons for calibration buttons
• Component Architecture: Created reusable TimerControlButton component
• Visual Effects: Grayscale/color effects with colored glow on hover (red/cyan)
• Assets Migration: Migrated role icons from Cloudinary to local assets

📝 Documentation

• Updated technical architecture documentation
• Added component usage examples

📦 Technical Changes

Backend:

• New DTO: AdjustTimerDto for adjustment validation
• New service method: adjustTimer(roomId, role, adjustment) in GameService
• New WebSocket event: game:adjust-timer in GameGateway
• Updated shared types: Added game:adjust-timer to ClientToServerEvents

Frontend:

• New component: TimerControlButton.component.tsx (reusable atomic button)
• New component: TimerControls.component.tsx (button container)
• Added adjustTimer function in GameContext for solo mode
• Added emitAdjustTimer in useSocket hook for multiplayer mode
• Integration in RoleCard with conditional rendering (only when cooldown is active)

Visual Design:

• Rest state: saturate-50 + brightness-90 + opacity-80 (subtle color retained)
• Hover: saturate-100 + brightness-110 + opacity-100 + glow (red/cyan)
• Active: scale-95 for tactile feedback
• Dynamic glow with inline boxShadow (Tailwind limitation bypass)

Modified Files:

File	Changes
apps/api/src/game/game.service.ts	Added adjustTimer + fake advance in useFlash
apps/api/src/game/game.gateway.ts	Handler game:adjust-timer
apps/api/src/game/dto/adjust-timer.dto.ts	New DTO
apps/api/libs/shared/src/types/socket.types.ts	New event
apps/web/features/game/components/timer-control-button.component.tsx	New component
apps/web/features/game/components/timer-controls.component.tsx	New component
apps/web/features/game/components/role-card.component.tsx	TimerControls integration
apps/web/features/game/contexts/game.context.tsx	Added adjustTimer function
apps/web/hooks/use-socket.hook.ts	Added emitAdjustTimer
apps/web/features/game/constants/game.constants.ts	Cloudinary → local assets migration

🎯 Impact

🟢 Major feature to improve timer precision and UX. Players can now manually adjust timers if they clicked late, and the 3-second fake advance compensates for human reaction time.

---

Full Changelog: https://github.com/yourusername/LolTimeFlash/compare/v2.2.0...v2.3.0

2.2.0 (Nov 22, 2025)

🐛 LolTimeFlash v2.2.0 - Timer Synchronization Fix

🔄 Overview

Critical bug fix resolving timer desynchronization issues across multiple devices and network conditions. Complete migration to a timestamp-based architecture ensures perfect sync across all clients.

🐛 Bug Fixes

• Fixed Timer Sync: Resolved timer desynchronization bug (5-10s drift between clients)
• Timestamp-Based Architecture: Complete migration to absolute timestamp system
• Dynamic Calculation: Countdowns now calculated dynamically with Date.now()
• Zero Time Drift: No more temporal drift thanks to per-tick recalculation
• Multiplayer Sync: Perfect synchronization across all clients (±1s max)
• Reconnection Resilience: Timestamps remain valid after reconnection/refresh

📝 Documentation

• Added timestamp architecture documentation
• Updated timer sync troubleshooting guide

📦 Technical Changes

Problem Identified:

Before this version, timers used a defective hybrid architecture:

• Backend: Stored timestamps (correct) ✅
• Frontend: Converted to countdown then decremented locally ❌

This caused 5-10 second drifts between devices after a few minutes of gameplay.

Solution Implemented:

// ❌ BEFORE: Conversion + local decrementation
const countdown = timestampToCountdown(backendRoleData.isFlashed)
const newValue = roleData.isFlashed - 1 // Each client decrements independently

// ✅ AFTER: Dynamic calculation based on timestamp
const isFlashedValue = backendRoleData.isFlashed // Store timestamp directly
const remainingSeconds = getRemainingTime(cooldown) // Calculate with current Date.now()

Modified Files:

File	Changes
use-flash-cooldown.hook.ts	Added getRemainingTime() helper
use-game-timer.hook.ts	Complete rewrite (no more decrementation)
game-multiplayer.screen.tsx	Removed timestamp → countdown conversion
game.context.tsx	useFlash and toggleItem timestamp-based
flash-button.component.tsx	Dynamic calculation + tick state for re-render
role-card.component.tsx	Cleanup console.log
game.types.ts	Timestamp semantic documentation

🎯 Impact

🟢 Critical bug resolved. Application now production-ready for multiplayer gameplay. All clients display identical timer values regardless of device, network conditions, or session duration.

---

Full Changelog: https://github.com/yourusername/LolTimeFlash/compare/v2.1.1...v2.2.0

2.1.1 (Nov 18, 2025)

📝 LolTimeFlash v2.1.1 - Documentation & Docker Fixes

🔄 Overview

Documentation update and critical Docker fixes to ensure production deployment reliability. Complete project documentation now available in README and AGENTS.md.

🐛 Bug Fixes

• Docker API Runtime: Fixed CMD path in apps/api/Dockerfile (dist/src/main)
• Docker Web TypeScript: Fixed TypeScript resolution (copy apps/api/libs for shared types)
• Package Scripts: Corrected start and start:prod scripts in apps/api/package.json

📝 Documentation

• README.md: Complete project overview and setup guide
• AGENTS.md: Comprehensive developer documentation (1638 lines)
• Shared Types Architecture: Documented flow with diagrams
• Demo Section: README ready for video/GIF marketing assets

📦 Technical Changes

Docker Fixes:

• Fixed apps/api/Dockerfile CMD path to use dist/src/main instead of dist/main
• Fixed apps/web/Dockerfile to copy shared types from apps/api/libs for TypeScript resolution
• Corrected apps/api/package.json scripts for production startup

Cleanup:

• Removed 5 temporary migration files
• Cleaned up obsolete documentation

Modified Files:

File	Changes
apps/api/Dockerfile	CMD path fix (dist/src/main)
apps/api/package.json	Scripts start/start:prod corrected
apps/web/Dockerfile	TypeScript resolution fix (copy apps/api/libs)
README.md	Complete rewrite with architecture details
AGENTS.md	1638 lines of developer documentation

🎯 Impact

✅ Docker test suite passes completely. Production deployment now reliable. Documentation complete for new contributors.

---

Full Changelog: https://github.com/yourusername/LolTimeFlash/compare/v2.0.0...v2.1.1

2.0.0 (Nov 15, 2025)

🚀 LolTimeFlash v2.0.0 - NestJS Monorepo Architecture

🔄 Overview

Major architecture refactor migrating to a NestJS monorepo with modular backend, shared types library, and optimized Docker deployment. This is a breaking change that restructures the entire backend infrastructure.

🚀 What's New

• Backend NestJS: Migration to NestJS 11.0 with modular architecture
• Monorepo Library: apps/api/libs/shared as single source of truth for types
• WebSocket Gateway: GameGateway with DTO validation and error handling
• Monitoring: Health checks, metrics, Winston logging with rotation
• Docker Optimized: Multi-stage builds, health checks, persistent volumes
• Type Safety: Shared types between API and Web (zero duplication)
• Turborepo: Parallel builds and intelligent caching

📝 Documentation

• Initial AGENTS.md with architecture overview
• Docker deployment guide
• Shared types architecture documentation

📦 Technical Changes

Backend Architecture:

• NestJS modules: Game, Room, Riot API, Monitoring, Logger
• WebSocket Gateway with Socket.IO 4.8.1
• DTO validation with class-validator
• Winston logger with daily rotation
• Health check endpoint: /monitoring/health

Shared Types:

• Location: apps/api/libs/shared (source of truth)
• Wrapper: packages/shared (for Next.js compatibility)
• Import aliases: @app/shared (API), @loltimeflash/shared (Web)

Docker:

• Multi-stage builds for API and Web
• Non-root users (UID/GID 1001)
• Health checks with retry logic
• Persistent volumes for logs
• Docker Compose orchestration

Monorepo:

• Turborepo for build orchestration
• pnpm workspace (9.10.0)
• Shared ESLint and TypeScript configs

Modified Files:

Component	Changes
Backend	Complete NestJS rewrite (6 modules)
Frontend	Updated imports to use shared types
Docker	Multi-stage Dockerfiles for API and Web
Build	Turborepo configuration
Types	Centralized in apps/api/libs/shared

⚠️ Breaking Changes

1. Backend Separation: API now runs on separate port (8888)
2. Environment Variables: Restructured .env file required
3. Docker Compose: Health checks now required for dependencies
4. Type Imports: Update imports to use @loltimeflash/shared

🔄 Migration Guide

Step 1: Install dependencies

pnpm install

Step 2: Update environment variables

# .env (project root)
PORT=8888
NODE_ENV=development
LOG_LEVEL=info
RIOT_API_KEY=your-key-here

Step 3: Test Docker setup

pnpm docker:test

Step 4: Run development servers

pnpm dev  # Runs both API and Web

🎯 Impact

🔴 Breaking changes require migration steps. However, the new architecture provides:

• ✅ Better separation of concerns
• ✅ Type safety across frontend and backend
• ✅ Production-ready monitoring and logging
• ✅ Scalable microservices architecture
• ✅ Optimized Docker deployment

---

Full Changelog: https://github.com/yourusername/LolTimeFlash/compare/v0.3.0...v2.0.0