Enh(viewer): Left/right buttons

Author: klieret

.cursor/rules/viewer.mdc

@@ -261,14 +261,37 @@ The application has two main pages:
 
 ### Keyboard Shortcuts
 
+#### Navigation Shortcuts
+* `h` or `←` (Left Arrow): Navigate to previous game in the folder structure
+* `l` or `→` (Right Arrow): Navigate to next game in the folder structure
 * `p` (lowercase): Open game picker in same tab (from viewer)
 * `P` (uppercase): Open game picker in new tab (from viewer)
+
+#### Interface Shortcuts
+* `?`: Show keyboard shortcuts help modal (available on both viewer and picker pages)
 * `t` (lowercase): Toggle floating table of contents
 * `Ctrl/Cmd + D`: Toggle dark/light mode
 * `Ctrl/Cmd + E`: Expand all sections
 * `Ctrl/Cmd + Shift + E`: Collapse all sections
 * `Escape`: Close all open sections
 
+### Keyboard Shortcuts Help Modal
+
+Both the viewer and picker pages include a help modal accessible via the `?` button or `?` keyboard shortcut:
+
+#### Modal Features
+* **Trigger**: `?` button in header or `?` keyboard shortcut
+* **Content**: Displays all available keyboard shortcuts organized by category
+* **Styling**: Bootstrap modal with consistent dark theme styling
+* **Dismissal**: Click outside modal, press Escape, or click close button
+* **Responsive**: Adapts to mobile screens appropriately
+
+#### Modal Content Structure
+* **Navigation Shortcuts**: Game navigation (h/←, l/→, p/P)
+* **Interface Shortcuts**: UI controls (?/t, Ctrl+E combinations, Escape)
+* **Mouse Shortcuts**: Click behaviors and multi-click actions
+* **Page-Specific Shortcuts**: Different content for viewer vs picker pages
+
 ### Floating Navigation
 
 * **Floating Table of Contents**: A floating navigation panel that provides quick navigation (always visible by default)
@@ -296,6 +319,12 @@ The application has two main pages:
 
 ## Game Picker Design (`/picker`)
 
+### Header
+
+* **Help button**: `?` button that shows keyboard shortcuts modal (same functionality as viewer page)
+* **Title**: "Pick a Game" with game controller icon
+* **Description**: Brief explanation of the picker functionality
+
 ### Features
 
 * **Hierarchical Tree Structure**: Shows all folders recursively with proper indentation
@@ -341,10 +370,18 @@ The application has two main pages:
 
 ### Header
 
-* **"Pick Game" button**: Navigate to picker (supports middle-click for new tab)
+#### Navigation Controls
+* **Previous/Next Game Buttons**: Navigate between games in alphabetical order within the folder structure
+  - **Previous button**: Shows `h` and `←` keyboard shortcut indicators, disabled when no previous game available
+  - **Next button**: Shows `l` and `→` keyboard shortcut indicators, disabled when no next game available
+  - **Button styling**: Uses Bootstrap secondary button styling, similar to Pick Game button
+* **"Pick Game" button**: Navigate to picker (supports middle-click for new tab) - positioned in the center between navigation buttons
   - Shows `p` keyboard shortcut indicator
   - Tooltip explains middle-click functionality
 * **"↗" button**: Always open picker in new tab
+* **Help button**: `?` button that shows keyboard shortcuts modal (available on both viewer and picker pages)
+
+#### Other Header Elements
 * **Dark/light mode toggle button**
 * **Current folder path display** with copy functionality, move/rename button, and delete button
   - **Move/Rename button**: 📁 icon that opens a dialog for moving or renaming the experiment folder (exact same functionality as in the game picker)
@@ -568,6 +605,25 @@ Both the game picker and trajectory viewer include move/rename functionality for
 - After successful move/rename in the trajectory viewer, the user is automatically redirected to the new folder path
 - The move/rename button appears in the folder path section alongside copy and delete buttons
 
+## Navigation Implementation Details
+
+### Game Navigation Logic
+* **Navigation Order**: Games are sorted alphabetically by their folder path within the logs directory
+* **Backend Function**: `get_navigation_info(selected_folder)` determines previous/next games
+* **Button States**: Navigation buttons are automatically disabled when no previous/next game is available
+* **URL Generation**: Supports both dynamic Flask routes (`/?folder=`) and static frozen routes (`/game/`)
+
+### Keyboard Shortcut Implementation
+* **Event Handling**: Single consolidated keyboard event listener to prevent conflicts
+* **Input Field Detection**: Shortcuts are disabled when typing in input fields or textareas
+* **Modal Priority**: Dialog shortcuts (Escape/Enter) take precedence when modals are open
+* **Arrow Key Support**: Both letter keys (h/l) and arrow keys (←/→) work for navigation
+
+### Button Layout
+* **Header Organization**: Navigation buttons (Previous, Pick Game, Next, Help) in logical left-to-right order
+* **Consistent Styling**: All buttons use Bootstrap classes with consistent kbd shortcut indicators
+* **Responsive Design**: Button layout adapts appropriately on mobile devices
+
 ### Important
 
 * Always use the player name from the metadata.json file, do not assume players are called p1, p2, etc.

codeclash/viewer/app.py

@@ -670,6 +670,29 @@ def unescape_content(value):
     return value.replace("\\n", "\n")
 
 
+def get_navigation_info(selected_folder: str) -> dict[str, str | None]:
+    """Get previous and next game folders for navigation"""
+    # Get all game folders
+    game_folders = find_all_game_folders(LOG_BASE_DIR)
+
+    # Filter to only actual game folders and sort them
+    game_names = [folder["name"] for folder in game_folders if folder["is_game"]]
+    game_names.sort()
+
+    # Find current game index
+    try:
+        current_index = game_names.index(selected_folder)
+    except ValueError:
+        # Current folder not found in the list
+        return {"previous": None, "next": None}
+
+    # Determine previous and next
+    previous_game = game_names[current_index - 1] if current_index > 0 else None
+    next_game = game_names[current_index + 1] if current_index < len(game_names) - 1 else None
+
+    return {"previous": previous_game, "next": next_game}
+
+
 def render_game_viewer(folder_path: Path, selected_folder: str) -> str:
     """Common logic for rendering game viewer pages"""
     # Parse the selected game
@@ -690,6 +713,9 @@ def render_game_viewer(folder_path: Path, selected_folder: str) -> str:
     sim_wins_data = parser.analyze_sim_wins_per_round()
     matrix_data = parser.load_matrix_analysis()
 
+    # Get navigation info
+    navigation_info = get_navigation_info(selected_folder)
+
     return render_template(
         "index.html",
         selected_folder=selected_folder,
@@ -699,6 +725,7 @@ def render_game_viewer(folder_path: Path, selected_folder: str) -> str:
         analysis_data=analysis_data,
         sim_wins_data=sim_wins_data,
         matrix_data=matrix_data,
+        navigation=navigation_info,
         is_static=STATIC_MODE,
     )
 

codeclash/viewer/static/css/picker.css

@@ -8,10 +8,21 @@
 }
 
 .picker-header {
-  text-align: center;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
   margin-bottom: 3rem;
 }
 
+.picker-title-section {
+  text-align: left;
+}
+
+.picker-controls {
+  display: flex;
+  align-items: center;
+}
+
 .picker-header h1 {
   color: var(--accent-color);
   font-size: 2rem;

codeclash/viewer/static/css/style.css

@@ -116,6 +116,27 @@ body {
   min-width: 120px;
 }
 
+/* Navigation buttons */
+.nav-button {
+  min-width: 60px;
+}
+
+.nav-button kbd {
+  background-color: rgba(255, 255, 255, 0.2);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 0.25rem;
+  padding: 0.125rem 0.25rem;
+  font-size: 0.75rem;
+  color: #ffffff;
+  font-weight: 600;
+}
+
+.nav-button:disabled kbd {
+  background-color: rgba(255, 255, 255, 0.1);
+  border: 1px solid rgba(255, 255, 255, 0.2);
+  color: #888888;
+}
+
 /* Let Bootstrap handle hover states */
 
 .pick-game-button kbd {
@@ -143,6 +164,91 @@ body {
   min-width: 40px;
 }
 
+/* Help button */
+.help-button {
+  min-width: 60px;
+}
+
+.help-button kbd {
+  background-color: rgba(255, 255, 255, 0.2);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 0.25rem;
+  padding: 0.125rem 0.25rem;
+  font-size: 0.75rem;
+  color: #ffffff;
+  font-weight: 600;
+}
+
+/* Help modal styling */
+.shortcut-section {
+  margin-bottom: 1.5rem;
+}
+
+.shortcut-section h6 {
+  color: var(--accent-color);
+  font-weight: 600;
+  margin-bottom: 0.75rem;
+  font-size: 1rem;
+}
+
+.shortcut-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.5rem 0;
+  border-bottom: 1px solid var(--border-color);
+}
+
+.shortcut-item:last-child {
+  border-bottom: none;
+}
+
+.shortcut-item kbd {
+  background-color: var(--bg-tertiary);
+  border: 1px solid var(--border-color);
+  border-radius: 0.25rem;
+  padding: 0.25rem 0.5rem;
+  font-size: 0.75rem;
+  color: var(--accent-color);
+  font-weight: 600;
+  margin-right: 0.5rem;
+}
+
+.shortcut-item .mouse-action {
+  background-color: var(--bg-tertiary);
+  border: 1px solid var(--border-color);
+  border-radius: 0.25rem;
+  padding: 0.25rem 0.5rem;
+  font-size: 0.75rem;
+  color: var(--text-secondary);
+  font-weight: 500;
+  margin-right: 0.5rem;
+}
+
+.shortcut-item span:last-child {
+  flex: 1;
+  text-align: left;
+  color: var(--text-primary) !important;
+}
+
+/* Bootstrap modal overrides for dark theme */
+.modal-content {
+  background-color: var(--bg-secondary) !important;
+  border: 1px solid var(--border-color) !important;
+}
+
+.modal-header {
+  border-bottom: 1px solid var(--border-color) !important;
+}
+
+.modal-title {
+  color: var(--text-primary) !important;
+}
+
+.modal-body {
+  color: var(--text-primary) !important;
+}
+
 /* Let Bootstrap handle hover states */
 
 /* Bootstrap handles most styling for theme toggle */