# 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).