working

README.md

@@ -1,108 +1,126 @@
-# OrreryTimer 🕰️✨
+# Nexus Timer 🕰️✨
 
-OrreryTimer is a dynamic multi-player timer designed for games, workshops, or any activity where turns pass sequentially in a circular fashion. It provides a clear visual focus on the current participant, their immediate predecessor and successor, and the direction of play, ensuring everyone stays engaged and aware of the flow.
-
-![OrreryTimer Mockup/Screenshot Placeholder](placeholder_screenshot.png)
-*(Replace with an actual screenshot or GIF once available)*
+Nexus Timer is a dynamic multi-player timer designed for games, workshops, or any activity where turns pass sequentially in a circular fashion. It provides a clear visual focus on the current participant and their immediate successor, ensuring everyone stays engaged and aware of who is next.
 
 ## Core Concept
 
-Inspired by an orrery (a mechanical model of the solar system), OrreryTimer visualizes players in a circular sequence. The "Current Player" is centrally featured, with the "Previous Player" and "Next Player" flanking them, clearly indicating the flow of turns. This tool is perfect for board games, round-robin discussions, timed presentations, or any scenario needing structured turn management with individual countdowns.
+Nexus Timer visualizes players in a circular sequence. The **Current Player** is prominently displayed in the top half of the screen, and the **Next Player** (their immediate successor) is in the bottom half. This clear visual pairing indicates the flow of turns, making it perfect for board games, round-robin discussions, timed presentations, or any scenario needing structured turn management with individual countdowns.
+
+## Hardware Recommendations (Optional Enhancement)
+
+For an enhanced tactile experience, Nexus Timer supports a Bluetooth-connected microcontroller (e.g., XIAO nRF52840) implementing HID (Human Interface Device) protocol.
+
+*   **Buttons:** Connect 3 physical buttons, potentially extended (e.g., via 1.5m wires) for easy player access.
+*   **Configuration (Example):**
+    *   **Player 1's Button:**
+        *   Single Click: Emulates a key press (e.g., 'a'). Configure this as Player 1's "Pass Turn / My Pause" hotkey in the app.
+    *   **Player 2's Button:**
+        *   Single Click: Emulates a key press (e.g., 'b'). Configure as Player 2's "Pass Turn / My Pause" hotkey.
+    *   **Player 3's Button:**
+        *   Single Click: Emulates a key press (e.g., 'c'). Configure as Player 3's "Pass Turn / My Pause" hotkey.
+        *   Long Press (if Player 3 is Game Admin): Emulates a key press (e.g., 's'). Configure as the "Global Stop/Pause All" hotkey in the app.
 
 ## Key Features ✨
 
 *   **Circular Player Display:**
-    *   Central focus on the **Current Player**.
-    *   Adjacent displays for **Previous** and **Next Players**.
-    *   Clear visual connection between these three roles.
-    *   Animated indicator showing the **direction of play** (clockwise/counter-clockwise).
+    *   Central focus on the **Current Player** (top) and **Next Player** (bottom).
 *   **Individual Player Timers:**
-    *   Each player has a customizable countdown timer (MM:SS).
-    *   Timers continue into **negative time** if the limit is reached (up to -59:59).
-    *   Players whose timers reach max negative time are "skipped" but remain visually present.
-    *   Visual feedback: Red pulsating effect for active timers (background for positive, text for negative).
+    *   Customizable countdown timer (MM:SS) for each player.
+    *   Timers continue into **negative time** (e.g., -MM:SS) up to a limit (e.g., -59:59).
+    *   Players reaching max negative time are **skipped** until reset or timer edit.
+    *   Visual feedback: Pulsating effect for active timers (background for positive, text for negative). Skipped players are visually distinct (e.g., greyed out).
 *   **Two Game Modes:**
-    1.  **Normal Mode (Single Active Timer):**
-        *   Only the Current Player's timer is active.
-        *   Pass turns via swipe gestures (left/right) or player-specific hotkeys.
-        *   Tap Current Player to pause/resume their timer.
+    1.  **Normal Mode (Default):**
+        *   Only the **Current Player's** timer runs.
+        *   Pass the turn via **Swipe Up** or the Current Player's "Pass Turn / My Pause" hotkey.
+        *   Tap Current Player's area or use "Global Stop/Pause All" hotkey to pause/resume their timer without passing the turn.
     2.  **All Timers Running Mode:**
-        *   All player timers start and run simultaneously.
-        *   Ideal for scenarios where everyone has a global time limit or races against each other.
-        *   Players can pause their *own* timer when they are current.
-        *   Global "Start All / Stop All" control.
-        *   App-wide visual (pulsating background) and audio (continuous ticking) cues when active.
+        *   All active player timers run simultaneously.
+        *   Enter by clicking "All Timers Mode" (starts all timers).
+        *   App-wide visual pulsing and continuous ticking sound when active.
+        *   **Swipe Up** to change which active player is "in focus" in the Current Player display.
+        *   Focused player can tap their area to pause their *own* timer. Any player can use their "Pass Turn / My Pause" hotkey to pause their *own* timer.
+        *   If all players pause their timers, automatically reverts to Normal Mode.
+        *   Main button: "Stop All Timers" (pauses all, returns to Normal Mode) or "Start All Timers" (resumes all in this mode). Can also be triggered by "Global Stop/Pause All" hotkey.
 *   **Player Management:**
-    *   Add, edit, and delete players (minimum 3, up to 10).
-    *   Upload player photos or use default avatars.
-    *   Set initial timer values per player.
-    *   Assign unique "Next Turn" hotkeys and non-unique "Stop My Timer" hotkeys.
-    *   Easily re-order players (drag-and-drop preferred).
+    *   Add, edit, and delete players (2-10 players).
+    *   Upload photos, use device camera, or default avatars.
+    *   Set initial timer values per player (Default: 60:00).
+    *   Assign unique "Pass Turn / My Pause" hotkeys.
+    *   Optionally designate one player as "Game Admin" for special hotkey functions.
+    *   Easily re-order (drag-and-drop planned), reverse, or shuffle player order.
 *   **Intuitive Controls:**
-    *   Swipe gestures for changing Current Player and turn direction in Normal Mode.
-    *   Tap interactions for timer control.
-    *   Global hotkey for "Stop All Timers."
+    *   **Swipe Up:** (On the Next Player's area). Primary gesture for passing turns (Normal Mode) or changing focus (All Timers Mode).
+    *   **On-Screen Taps:** (On the Current Player's area). For pausing/resuming timers contextually.
 *   **Audio Feedback:**
-    *   Continuous ticking in "All Timers Running Mode."
-    *   3-second alert tick when a timer becomes active in "Normal Mode."
-    *   Option to mute all sounds.
-*   **Persistence:** Player configurations, current timer states, and game settings are saved locally, so your setup is ready when you reopen the app.
-*   **Global Reset:** A "Reset Game" button to revert all timers to initial values and reset the game state.
+    *   Continuous ticking in "All Timers Running Mode" when active.
+    *   Brief 3-second tick when a timer starts in Normal Mode. Cancel the sound when the timer pauses.
+    *   Global mute option.
+*   **Persistence:** Player setups, timer states, and settings are saved locally.
+*   **Global Reset:** "Reset Game" button restores all timers to initial values and resets game state.
 
 ## Tech Stack (Planned/Example)
 
+*   Progressive Web App (PWA) for smartphone screens.
+*   Modular codebase.
+*   Simple sounds using pure Web Audio API.
+*   CSS for styling, animations, and placeholder avatars.
+*   Local Storage/IndexedDB for persistence.
+
 ## Getting Started
 
 **(Details to be added once development begins)**
 
 1.  **Prerequisites:**
-    * 
+    *   A modern web browser on a smartphone or tablet.
+    *   (Optional) Bluetooth-enabled microcontroller for hardware buttons.
 2.  **Installation:**
     ```bash
-    git clone https://gitea.virtonline.eu/2HoursProject/OrreryTimer.git
-    cd OrreryTimer
-
+    # Placeholder for PWA installation instructions or link
     ```
 3.  **Running the Application:**
     ```bash
-
+    # Placeholder for how to access/run the app
     ```
 
 ## Usage Guide
 
 1.  **Manage Players:**
-    *   Click "Manage Players."
-    *   Add at least 3 players. For each player:
-        *   Enter a name.
-        *   Optionally, upload a photo.
-        *   Set their initial timer duration.
-        *   Optionally, assign a "Next Turn" hotkey (must be unique) and a "Stop My Timer" hotkey.
-    *   Arrange players in the desired turn order.
+    *   Tap "Manage Players."
+    *   Add players: Enter name, set initial timer. Optionally, add a photo, assign a "Pass Turn / My Pause" hotkey, and designate an admin.
+    *   Edit existing players or change their order.
     *   Save changes.
 2.  **Main Screen:**
-    *   The Current, Previous, and Next players will be displayed.
-    *   The turn direction indicator shows the flow.
+    *   The **Current Player** appears in the top half, **Next Player** in the bottom. Effective use of the phone's screen. No additional elements like header or footer.
 3.  **Normal Mode (Default):**
     *   Tap the Current Player's area to start/pause their timer.
-    *   Swipe left or right on the Current Player's area to pass the turn and set the direction. The new Current Player's timer will start/resume.
-    *   If the Current Player has a "Next Turn" hotkey, pressing it will pass the turn.
+    *   To pass the turn: **Swipe Up** on the Next Player's area or have the Current Player press their "Pass Turn / My Pause" hotkey. The current timer pauses, the next player becomes Current, and their timer starts.
+    *   Click the "All Timers Mode" button to switch modes (this will also start all timers).
 4.  **All Timers Running Mode:**
-    *   Click "Start All Timers." All player timers will begin counting down.
-    *   The app background will pulse red, and a ticking sound will play.
-    *   When it's a player's "focus" as Current Player, they can tap their area or use their "Stop My Timer" hotkey to pause their *own* timer. The focus will then shift to the next player with a running timer.
-    *   Click "Stop All Timers" (or use the global hotkey) to pause all running timers.
+    *   All active player timers run. The app background pulses, and a ticking sound plays (if unmuted).
+    *   The "Current Player" area shows one of the players with an active timer. **Swipe Up** to cycle focus to other players with active timers.
+    *   A player can pause their *own* timer by:
+        *   Tapping their display area (if they are the focused Current Player).
+        *   Pressing their "Pass Turn / My Pause" hotkey.
+    *   If all players pause their timers, the app reverts to Normal Mode.
+    *   The main control button will say "Stop All Timers." Clicking it (or using the "Global Stop/Pause All" hotkey) pauses all timers and returns to Normal Mode. If all timers are already paused in this mode, it says "Start All Timers."
 5.  **Reset Game:**
-    *   Click "Reset Game" and confirm to restore all timers to their initial values and reset player positions.
+    *   Tap "Reset Game" and confirm to restore all timers to their initial values.
 
 ## Configuration
 
-*   **Player Hotkeys:** Configured in the "Add/Edit Player" form.
-    *   "Next Turn" Key: Advances to the next player in Normal Mode.
-    *   "Stop My Timer" Key: Pauses the current player's timer in All Timers Running Mode.
-*   **Global "Stop All" Hotkey:** [Specify default, e.g., 'Escape' or 'S'] - this pauses all timers in any mode.
-*   **Audio Mute:** Look for a settings icon or option to mute all sounds.
+*   **Player Hotkeys (in "Manage Players"):**
+    *   **"Pass Turn / My Pause" Key:**
+        *   Normal Mode: If pressed by Current Player, passes the turn.
+        *   All Timers Mode: Pauses/resumes the respective player's own timer.
+*   **Global Hotkeys (configured in settings or player management for admin):**
+    *   **"Global Stop/Pause All" Hotkey:**
+        *   Normal Mode: Pauses the Current Player's timer.
+        *   All Timers Mode (timers running): Pauses all timers and returns to Normal Mode.
+        *   All Timers Mode (all timers paused): Resumes all timers in All Timers Mode.
+*   **Audio Mute:** Look for a mute/unmute icon or setting.
 
 ## Future Enhancements 🚀
 
 *   Light/Dark theme options.
-*   Ability to save and load different game setups (player lists & timer configurations).
+*   Game statistics (e.g., average turn time).