feat: persist state

Signed-off-by: Jonathan Irvin <[email protected]>

Author: jonathan-irvin

.gitignore

@@ -52,3 +52,4 @@ Thumbs.db
 
 # Poetry lock file (optional – some teams prefer to version-control this)
 poetry.lock
+.nicegui/

CONTEXT.md

@@ -0,0 +1,45 @@
+# BINGO App Context
+
+## State Persistence
+- Game state is persisted across app restarts using `app.storage.general`
+- Clicked tiles, game status (open/closed), and header text are saved
+- Implemented serialization/deserialization for Python types (sets, tuples)
+- Key functions (toggle_tile, reset_board, close_game) save state after changes
+- App initialization loads state from storage if available
+
+## View Synchronization
+- Two main views: root (/) and stream (/stream)
+- NiceGUI 2.11+ compatibility implemented (removed ui.broadcast())
+- Timer-based synchronization at 0.05 second intervals
+- sync_board_state() handles synchronization between views
+- Both views reflect same game state, header text, and board visibility
+
+## User Connection Tracking
+- Connected users tracked on both root and stream paths
+- Connection/disconnection handled properly
+- Health endpoint reports active user counts
+- UI displays active user count
+- Maintains lists of active user sessions
+
+## Mobile UI Improvements
+- Control buttons include text alongside icons
+- Improved button styling for better touch targets
+- Clearer tooltips with descriptive text
+- Consistent styling between game states
+
+## Key Functions
+- save_state_to_storage() - Serializes game state to app.storage.general
+- load_state_from_storage() - Loads and deserializes state from storage
+- toggle_tile() - Updates state and uses timer-based sync
+- close_game() - Saves state and updates synchronized views
+- reopen_game() - Restores state across synchronized views
+- home_page() - Includes user tracking functionality
+- stream_page() - Includes user tracking functionality
+- health() - Reports system status including active users
+
+## Testing
+- State persistence tests verify storage functionality
+- Synchronization tests ensure consistent views
+- NiceGUI 2.11+ compatibility tests
+- UI component tests for controls and board
+- User tracking tests for connection handling

NICEGUI_NOTES.md

@@ -0,0 +1,74 @@
+# NiceGUI Documentation Notes
+
+## Version: 2.11.0
+
+## Key Features and APIs
+
+### app.storage
+- Built-in persistent storage system
+- Available as `app.storage.general` for general-purpose storage
+- Automatically persists across app restarts
+- Usage:
+  ```python
+  # Store data
+  app.storage.general['key'] = value
+  
+  # Retrieve data
+  value = app.storage.general.get('key', default_value)
+  
+  # Check if key exists
+  if 'key' in app.storage.general:
+      # ...
+  ```
+- Storage is JSON-serializable, must handle conversion of non-JSON types (like sets)
+
+### Client Synchronization
+- `ui.timer(interval, callback)`: Runs a function periodically (interval in seconds)
+- `app.on_disconnect(function)`: Registers a callback for when client disconnects
+- In NiceGUI 2.11+, updates to UI elements are automatically pushed to all clients
+- Use timers for periodic synchronization between clients
+- For immediate updates across clients, use a smaller timer interval (e.g., 0.05 seconds)
+
+### UI Controls
+- Buttons support both text and icons:
+  ```python
+  ui.button("Text", icon="icon_name", on_click=handler)
+  ```
+- Mobile-friendly practices:
+  - Use larger touch targets (at least 44x44 pixels)
+  - Add descriptive text to icons
+  - Use responsive classes
+
+## Best Practices
+
+### State Management
+1. Store state in app.storage.general for persistence
+2. Convert Python-specific types (sets, tuples) to JSON-compatible types:
+   - Sets → Lists
+   - Tuples → Lists
+3. Convert back when loading
+4. Handle serialization errors gracefully
+
+### Synchronization Between Views
+1. NiceGUI 2.11+ automatically synchronizes UI element updates between clients
+2. Use timers for consistent state synchronization
+3. For best results, combine:
+   - Fast timers (0.05 seconds) for responsive updates
+   - Shared state in app.storage for persistence
+   - State loading on page initialization
+
+### Error Handling
+1. Wrap storage operations in try/except
+2. Handle disconnected clients gracefully
+3. Log issues with appropriate level (debug vs error)
+
+### Testing
+1. Mock app.storage for unit tests
+2. Test serialization/deserialization edge cases
+3. Simulate app restarts for integration tests
+
+## Documentation References
+- Full API Documentation: https://nicegui.io/documentation
+- State Management: https://nicegui.io/documentation#app_storage
+- Timers and Async: https://nicegui.io/documentation#ui_timer
+- Broadcasting: https://nicegui.io/documentation#ui_broadcast

app.py

@@ -17,6 +17,7 @@
     generate_board,
     is_game_closed,
     today_seed,
+    load_state_from_storage,
 )
 from src.ui.routes import init_routes
 from src.utils.file_operations import read_phrases_file
@@ -30,10 +31,18 @@
 # Initialize the application
 def init_app():
     """Initialize the Bingo application."""
-
-    # Initialize game state
-    phrases = read_phrases_file()
-    generate_board(board_iteration, phrases)
+    # Ensure storage is initialized
+    if not hasattr(app.storage, 'general'):
+        app.storage.general = {}
+
+    # Try to load state from storage first
+    if load_state_from_storage():
+        logging.info("Game state loaded from persistent storage")
+    else:
+        # If no saved state exists, initialize fresh game state
+        logging.info("No saved state found, initializing fresh game state")
+        phrases = read_phrases_file()
+        generate_board(board_iteration, phrases)
 
     # Initialize routes
     init_routes()
@@ -48,4 +57,4 @@ def init_app():
 if __name__ in {"__main__", "__mp_main__"}:
     # Run the NiceGUI app
     init_app()
-    ui.run(port=8080, title=f"{HEADER_TEXT}", dark=False)
+    ui.run(port=8080, title=f"{HEADER_TEXT}", dark=False, storage_secret=os.getenv("STORAGE_SECRET","ThisIsMyCrappyStorageSecret"))

src/core/game_logic.py

@@ -5,9 +5,10 @@
 import datetime
 import logging
 import random
-from typing import List, Optional, Set, cast
+import json
+from typing import List, Optional, Set, Dict, Any, Tuple, cast
 
-from nicegui import ui
+from nicegui import ui, app
 
 from src.config.constants import (
     CLOSED_HEADER_TEXT,
@@ -103,6 +104,9 @@ def toggle_tile(row: int, col: int) -> None:
         clicked_tiles.add(key)
 
     check_winner()
+    
+    # Save state to storage after each tile toggle for persistence
+    save_state_to_storage()
 
     for view_key, (container, tile_buttons_local) in board_views.items():
         for (r, c), tile in tile_buttons_local.items():
@@ -143,6 +147,10 @@ def toggle_tile(row: int, col: int) -> None:
             }, 50);
         """
         ui.run_javascript(js_code)
+        
+        # In NiceGUI 2.11+, updates are automatically synchronized between clients
+        # via the timer-based sync_board_state function running frequently
+        logging.debug("UI updates will be synchronized by timers")
     except Exception as e:
         logging.debug(f"JavaScript execution failed: {e}")
 
@@ -265,6 +273,9 @@ def reset_board() -> None:
         for c, phrase in enumerate(row):
             if phrase.upper() == FREE_SPACE_TEXT:
                 clicked_tiles.add((r, c))
+    
+    # Save state after reset for persistence
+    save_state_to_storage()
 
 
 def generate_new_board(phrases: List[str]) -> None:
@@ -322,19 +333,17 @@ def close_game() -> None:
     if controls_row is not None:
         controls_row.clear()
         with controls_row:
-            with ui.button("", icon="autorenew", on_click=reopen_game).classes(
-                "rounded-full w-12 h-12"
+            with ui.button("Start New Game", icon="autorenew", on_click=reopen_game).classes(
+                "px-4 py-2"
             ) as new_game_btn:
-                ui.tooltip("Start New Game")
+                ui.tooltip("Start a new game with a fresh board")
 
-    # Update stream page as well - this will trigger sync_board_state on connected clients
-    # Note: ui.broadcast() was used in older versions of NiceGUI, but may not be available
-    try:
-        ui.broadcast()  # Broadcast changes to all connected clients
-    except AttributeError:
-        # In newer versions of NiceGUI, broadcast might not be available
-        # We rely on the timer-based sync instead
-        logging.info("ui.broadcast not available, relying on timer-based sync")
+    # Save game state with is_game_closed=True for persistence
+    save_state_to_storage()
+
+    # In NiceGUI 2.11+, updates are automatically synchronized between clients
+    # via the timer-based sync_board_state function
+    logging.info("Game closed - changes will be synchronized by timers")
 
     # Notify that game has been closed
     ui.notify("Game has been closed", color="red", duration=3)
@@ -385,11 +394,86 @@ def reopen_game() -> None:
     # Notify that a new game has started
     ui.notify("New game started", color="green", duration=3)
 
-    # Update stream page and all other connected clients
-    # This will trigger sync_board_state on all clients including the stream view
+    # In NiceGUI 2.11+, updates are automatically synchronized between clients
+    # via the timer-based sync_board_state function
+    logging.info("Game reopened - changes will be synchronized by timers")
+        
+    # Save state to storage for persistence across app restarts
+    save_state_to_storage()
+
+
+def save_state_to_storage() -> bool:
+    """
+    Save the current game state to app.storage.general for persistence
+    across application restarts.
+    
+    Returns:
+        bool: True if state was saved successfully, False otherwise
+    """
+    try:
+        if not hasattr(app, 'storage') or not hasattr(app.storage, 'general'):
+            logging.warning("app.storage.general not available")
+            return False
+        
+        # Convert non-JSON-serializable types to serializable equivalents
+        clicked_tiles_list = list(tuple(coord) for coord in clicked_tiles)
+        bingo_patterns_list = list(bingo_patterns)
+        
+        # Prepare state dictionary
+        state = {
+            'board': board,
+            'clicked_tiles': clicked_tiles_list,
+            'bingo_patterns': bingo_patterns_list,
+            'board_iteration': board_iteration,
+            'is_game_closed': is_game_closed,
+            'today_seed': today_seed
+        }
+        
+        # Save to storage
+        app.storage.general['game_state'] = state
+        logging.debug("Game state saved to persistent storage")
+        return True
+    except Exception as e:
+        logging.error(f"Error saving state to storage: {e}")
+        return False
+
+
+def load_state_from_storage() -> bool:
+    """
+    Load game state from app.storage.general if available.
+    
+    Returns:
+        bool: True if state was loaded successfully, False otherwise
+    """
+    global board, clicked_tiles, bingo_patterns, board_iteration, is_game_closed, today_seed
+    
     try:
-        ui.broadcast()  # Broadcast changes to all connected clients
-    except AttributeError:
-        # In newer versions of NiceGUI, broadcast might not be available
-        # We rely on the timer-based sync instead
-        logging.info("ui.broadcast not available, relying on timer-based sync")
+        if not hasattr(app, 'storage') or not hasattr(app.storage, 'general'):
+            logging.warning("app.storage.general not available")
+            return False
+        
+        if 'game_state' not in app.storage.general:
+            logging.debug("No saved game state found in storage")
+            return False
+        
+        state = app.storage.general['game_state']
+        
+        # Load board
+        board = state['board']
+        
+        # Convert clicked_tiles from list back to set
+        clicked_tiles = set(tuple(coord) for coord in state['clicked_tiles'])
+        
+        # Convert bingo_patterns from list back to set
+        bingo_patterns = set(state['bingo_patterns'])
+        
+        # Load other state variables
+        board_iteration = state['board_iteration']
+        is_game_closed = state['is_game_closed']
+        today_seed = state['today_seed']
+        
+        logging.debug("Game state loaded from persistent storage")
+        return True
+    except Exception as e:
+        logging.error(f"Error loading state from storage: {e}")
+        return False

src/ui/controls.py

@@ -27,18 +27,18 @@ def create_controls_row():
     phrases = read_phrases_file()
 
     with ui.row().classes("w-full mt-4 items-center justify-center gap-4") as row:
-        with ui.button("", icon="refresh", on_click=lambda: reset_board()).classes(
-            "rounded-full w-12 h-12"
+        with ui.button("Reset", icon="refresh", on_click=lambda: reset_board()).classes(
+            "px-4 py-2"
         ) as reset_btn:
-            ui.tooltip("Reset Board")
+            ui.tooltip("Reset the board while keeping the same phrases")
         with ui.button(
-            "", icon="autorenew", on_click=lambda: generate_new_board(phrases)
-        ).classes("rounded-full w-12 h-12") as new_board_btn:
-            ui.tooltip("New Board")
-        with ui.button("", icon="close", on_click=close_game).classes(
-            "rounded-full w-12 h-12 bg-red-500"
+            "New Board", icon="autorenew", on_click=lambda: generate_new_board(phrases)
+        ).classes("px-4 py-2") as new_board_btn:
+            ui.tooltip("Generate a completely new board")
+        with ui.button("Close Game", icon="close", on_click=close_game).classes(
+            "px-4 py-2 bg-red-500"
         ) as close_btn:
-            ui.tooltip("Close Game")
+            ui.tooltip("Close the game for all viewers")
         ui_seed_label = (
             ui.label(f"Seed: {today_seed}")
             .classes("text-sm text-center")
@@ -64,18 +64,18 @@ def rebuild_controls_row(row):
 
     row.clear()
     with row:
-        with ui.button("", icon="refresh", on_click=lambda: reset_board()).classes(
-            "rounded-full w-12 h-12"
+        with ui.button("Reset", icon="refresh", on_click=lambda: reset_board()).classes(
+            "px-4 py-2"
         ) as reset_btn:
-            ui.tooltip("Reset Board")
+            ui.tooltip("Reset the board while keeping the same phrases")
         with ui.button(
-            "", icon="autorenew", on_click=lambda: generate_new_board(phrases)
-        ).classes("rounded-full w-12 h-12") as new_board_btn:
-            ui.tooltip("New Board")
-        with ui.button("", icon="close", on_click=close_game).classes(
-            "rounded-full w-12 h-12 bg-red-500"
+            "New Board", icon="autorenew", on_click=lambda: generate_new_board(phrases)
+        ).classes("px-4 py-2") as new_board_btn:
+            ui.tooltip("Generate a completely new board")
+        with ui.button("Close Game", icon="close", on_click=close_game).classes(
+            "px-4 py-2 bg-red-500"
         ) as close_btn:
-            ui.tooltip("Close Game")
+            ui.tooltip("Close the game for all viewers")
         ui_seed_label = (
             ui.label(f"Seed: {today_seed}")
             .classes("text-sm text-center")