working

README.md.orig

@@ -0,0 +1,126 @@
+# Nexus Timer 🕰️✨
+
+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
+
+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** (top) and **Next Player** (bottom).
+*   **Individual Player Timers:**
+    *   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 (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 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 (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 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" 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
+    # 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:**
+    *   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 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.
+    *   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:**
+    *   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:**
+    *   Tap "Reset Game" and confirm to restore all timers to their initial values.
+
+## Configuration
+
+*   **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.
+*   Game statistics (e.g., average turn time).