# 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. This document serves as a detailed specification for a Progressive Web App (PWA) prototype aimed at game enthusiasts.

## 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** is in the bottom half. This clear visual pairing indicates the flow of turns, making it perfect for board games, role-playing games, timed presentations, or any scenario needing structured turn management with individual countdowns.

## Target Audience

Game enthusiasts who play turn-based games (board games, tabletop RPGs, card games) and need a visually clear and customizable timer solution.

## Tech Stack

*   **HTML5:**  For structuring the user interface.
*   **CSS3:** For styling and visual presentation, including animations.  Consider a CSS framework like Tailwind CSS for rapid prototyping.
*   **JavaScript:** For application logic, timer functionality, and event handling.
*   **Web Audio API:** For audio feedback (ticking sounds, alerts).
*   **Browser API:** For capturing Players' photo.
*   **Local Storage/IndexedDB:** For persistent storage of player data, timer states, and settings.
*   **Service Worker:**  Essential for PWA functionality (offline access, push notifications - potential future feature).
*   **Manifest File:**  Defines the PWA's metadata (name, icons, theme color).
*   **Web Framework:**  Use Vue.js
*   **(Optional) Tailwind CSS:** Utility-first CSS framework for rapid UI development.

## Hardware Recommendations (Optional Enhancement)

For an enhanced tactile experience, Nexus Timer supports Smart Buttons based on 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:**
    *   **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:**
    1.  **Normal Mode (Default):** Central focus on the **Current Player** (top) and **Next Player** (bottom).
    2.  **All Timers Running Mode:** List of players with running timers.
*   **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** on the Next Player's area or the Current Player's "Pass Turn / My Pause" hotkey.
        *   3-seconds ticking sound when the timer starts to alert players about the "Pass Turn".
        *   Tap Current Player's area or use "Global Stop/Pause All" hotkey to pause/resume their timer without passing 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.
    2.  **All Timers Running Mode:**
        *   All active player timers run simultaneously.
        *   Enter by clicking "All Timers Mode" (starts all timers).
        *   Continuous ticking sound when active.
        *   Initially, all players are shown in a list with their photo, name and timer value.
        *   Tapping on a player in the list pauses its timer. Any player can use their "Pass Turn / My Pause" hotkey to pause their *own* timer.
        *   Only players with a running timer are shown in the list.
        *   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-7 players).
    *   Use device camera (access via browser API) or default avatars for the player's picture.
    *   Set initial timer values per player (Default: 60:00).
    *   Assign unique "Pass Turn / My Pause" hotkeys (single keypresses). E.g.: Use the Player's 1 "single click" action to insert the key.
    *   Assign the "Global Stop/Pause All" hotkey (single keypresses). E.g.: Use the Player's 3 "long press" action to insert the key.
    *   Re-order players (drag-and-drop planned), reverse, shuffle.
*   **Intuitive Controls:**
    *   **Swipe Up:** (On the Next Player's area). Primary gesture for passing turns (Normal 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.
*   **Visuals:**
    *   Designed for mobile phone screens (portrait orientation).
    *   Light/Dark theme options.
*   **Persistence:** Player setups, timer states, and settings are saved locally using browser Local Storage.
*   **Global Reset:** "Reset Game" button restores all timers to initial values and resets game state.

## UI/UX Considerations (For AI Generation)

*   **Minimalist Design:** Focus on clarity and ease of use. Avoid clutter.
*   **Large, Clear Timers:**  Timers should be easily readable at a glance.
*   **Color Coding:** Use color to indicate timer state (e.g., green for running, red for negative time, grey for skipped).
*   **Responsive Layout:**  The UI should adapt to different (mobile phone) screen sizes.
*   **Touch-Friendly:**  Buttons and interactive elements should be large enough for easy tapping.

## Data Model (For AI Generation)

```json
{
  "players": [
    {
      "id": "1",
      "name": "Alice",
      "avatar": "image",
      "initialTimer": "60:00",
      "currentTimer": "60:00",
      "hotkey": "a",
      "isSkipped": false
    },
    {
      "id": "2",
      "name": "Bob",
      "avatar": "image",
      "initialTimer": "60:00",
      "currentTimer": "60:00",
      "hotkey": "b",
      "isSkipped": false
    }
  ],
  "globalHotkey": "s",
  "currentPlayerIndex": 0,
  "gameMode": "normal", // "normal" or "allTimers"
  "isMuted": false
}
```
## Installation
Build the app with docker

```bash
docker build -t nexus-timer .
```