User Guide
Relevant source files
The following files were used as context for generating this wiki page:Endfield-Pomodoro is an immersive web-based Pomodoro timer application inspired by Cyber UI and the game Arknights: Endfield. It combines a productivity timer with a task manager and a music player, all wrapped in a highly stylized, futuristic terminal interface. The application is built with React, TypeScript, and TailwindCSS, and it supports PWA for offline use.
This guide provides a comprehensive overview of the application's features, controls, and configuration options. All data, including settings, tasks, and Pomodoro session progress, is persisted locally in your browser's localStorage.
Sources: README.md, src/App.tsx:10-29, index.html:5
🚀 Getting Started
To run the application locally, you need Node.js (version >= 18) and a package manager like pnpm.
-
Clone the repository:
git clone https://github.com/ChuwuYo/Endfield-Pomodoro.git cd endfield-pomodoro -
Install dependencies:
pnpm install -
Start the development server:
pnpm devThe application will be available at
http://localhost:5173.
Sources: README.md:60-78, package.json:5-8
✨ Core Features
The application is divided into several modules, accessible from the main dashboard.
| Feature | Description | Main Component |
|---|---|---|
| Pomodoro Timer | A configurable timer with work, short break, and long break modes. | src/components/Pomodoro.tsx |
| Task Manager | A simple to-do list to manage current objectives. | src/components/TaskManager.tsx |
| Audio Player | A music player with local file and online streaming support. | src/components/AudioPlayer.tsx |
| System Configuration | A settings panel to customize all aspects of the application. | src/App.tsx |
Sources: README.md:16-31
🍅 Pomodoro Timer (Chrono Module)
The Pomodoro timer is the central feature of the application. It helps you manage work and break intervals to maintain focus.
Sources: src/components/Pomodoro.tsx
Timer Modes and Flow
The timer operates in a cycle of three modes: Work, Short Break, and Long Break. After a work session is completed, the application automatically transitions to a break. A long break is initiated after every 4 work sessions (LONG_BREAK_INTERVAL).
The diagram below illustrates the Pomodoro state transitions.
This diagram shows the automatic cycle and manual user actions for the Pomodoro timer.
Sources: src/components/Pomodoro.tsx:210-224, src/constants.ts:4
Interface and Controls
The timer is displayed as a large circular progress ring with the remaining time in the center.
- Status Display: Shows the current mode (
OPERATIONAL,COOLDOWN,HIBERNATION) or state (STANDBY,PAUSED). - Progress Ring: A circular bar visually represents the time elapsed. It glows and pulses when the timer is active.
- Sessions Completed: A counter for completed work cycles.
- Controls:
- INITIALIZE / HALT: Starts or pauses the timer.
- RESET TIMER: Resets the current timer to its full duration.
- SKIP TO NEXT: Immediately ends the current session and moves to the next one in the cycle.
- RESET CYCLES: Resets the completed session count to zero.
Sources: src/components/Pomodoro.tsx:266-383, src/utils/i18n.ts:70-76, 99-104
Data Persistence
The timer's state (mode, timeLeft, isActive) is automatically saved to localStorage. If you refresh the page, the timer will restore its state, calculating any time that has passed while the page was closed. Total focus time is also tracked and displayed in the footer.
Sources: src/components/Pomodoro.tsx:44-100, 103-121, src/App.tsx:103-112, 258-261
📋 Task Manager (Mission Protocols)
The task manager allows you to list up to 6 objectives to focus on.
- Add Task: Enter a task description in the input field and press
Enteror click theADDbutton. - Toggle Task: Click the square checkbox next to a task to mark it as complete or incomplete.
- Delete Task: Hover over a task and click the
Xicon to remove it. - Clear Completed: A button appears at the bottom to remove all completed tasks at once.
Tasks are persisted in localStorage under the key origin_terminal_tasks.
Sources: src/components/TaskManager.tsx:12, 29-31, 44-59
🎵 Audio Player (Audio Feed)
The audio player supports two modes: Local and Online.
- Local Mode: You can load audio files from your computer.
- Online Mode: Streams music from a configured online playlist (e.g., NetEase Cloud Music, QQ Music). This mode is only available when the application is online.
The player interface provides standard controls:
- Play/Pause, Next/Previous Track
- Seekable progress bar
- Volume control with mute toggle
- Playback mode toggle (Sequential, Shuffle, Repeat One)
- Playlist view toggle
Sources: README.md:22-28, src/components/PlayerInterface.tsx, src/App.tsx:645-648
⚙️ System Configuration
All settings are accessible via the SYSTEM CONFIG view. Changes are saved to localStorage and applied immediately.
The following diagram shows how settings are loaded, updated, and persisted.
This diagram illustrates the flow of loading and saving user settings.
Sources: src/App.tsx:71-88, 203-209
Cycle Parameters
These settings control the duration of the Pomodoro timer intervals.
| Setting | UI Label | Default Value | Description |
|---|---|---|---|
workDuration | WORK CYCLE (MIN) | 25 | Duration of a work session in minutes. |
shortBreakDuration | MAINTENANCE (S) | 5 | Duration of a short break in minutes. |
longBreakDuration | REBOOT (L) | 15 | Duration of a long break in minutes. |
Sources: src/App.tsx:32-35, 439-467, src/utils/i18n.ts:11-13
Automation & Feedback
| Setting | UI Label | Default Value | Description |
|---|---|---|---|
autoStartBreaks | AUTO-START BREAKS | true | Automatically start break sessions after a work session ends. |
autoStartWork | AUTO-START WORK | true | Automatically start work sessions after a break ends. |
soundEnabled | SFX SYSTEM | true | Enable/disable sound effects for timer events (start, end). |
notificationsEnabled | DESKTOP NOTIFICATIONS | false | Enable/disable browser notifications when a session completes. Requires user permission. |
Sources: src/App.tsx:36-40, 521-568, src/utils/i18n.ts:14-17
Interface Customization
| Setting | UI Label | Default Value | Description |
|---|---|---|---|
language | LANGUAGE | en or cn | Sets the display language (English or Chinese). Detected from browser language on first visit. |
theme | UI THEME | INDUSTRIAL | Changes the visual theme (colors and effects) of the application. |
Sources: src/App.tsx:40-44, 484-518, src/utils/i18n.ts:18-19
Online Music Configuration
These settings configure the online music streaming feature.
| Setting | UI Label | Default Value | Description |
|---|---|---|---|
server | PLATFORM | netease | The music service provider. |
type | TYPE | playlist | The type of content to fetch (only 'playlist' is supported). |
id | ID | 9094583817 | The ID of the playlist. |
Sources: src/App.tsx:45, 571-616, src/utils/i18n.ts:21-24
🎨 Theme System
The application features a dynamic theme system that uses CSS Variables to change the look and feel. Each theme defines a set of colors and can include unique background and foreground visual effects.
Sources: src/index.css:12-25, README.md:155-171
The following themes are available:
| Theme Constant | UI Label | Description |
|---|---|---|
ThemePreset.ORIGIN | PRESET_01: ENDFIELD_PROTOCOL | The default Endfield theme with a grid background and mouse-following halo. |
ThemePreset.AZURE | PRESET_02: AZURE_ARCHIVE | A light blue theme with a grid and a vertical scanning line effect. |
ThemePreset.NEON | PRESET_03: NEON_CITY | A dark, neon-lit theme. |
ThemePreset.MATRIX | PRESET_04: MATRIX_CODE | A dark theme with a "digital rain" background effect. |
ThemePreset.TACTICAL | PRESET_05: DESERT_OPS | A desert-themed UI with a tactical grid and a crosshair that follows the mouse. |
ThemePreset.ROYAL | PRESET_06: ROYAL_VIOLET | A purple and gold theme with particle effects. |
ThemePreset.INDUSTRIAL | PRESET_07: HEAVY_INDUSTRY (LIGHT) | A light, industrial gray theme with warning-stripe effects. |
ThemePreset.LABORATORY | PRESET_08: SCIENCE_LAB (LIGHT) | A clean, light theme with scientific grid patterns and an analysis spotlight. |
ThemePreset.MIKU | PRESET_09: MIKU | A special theme featuring Hatsune Miku, with a hex grid, equalizer bars, and character art. |
Sources: src/utils/i18n.ts:41-51, src/components/TerminalUI.tsx, src/components/themes/ForegroundEffects.tsx, src/components/MikuDecorations.tsx
📱 PWA Support
The application can be installed as a Progressive Web App (PWA), allowing it to be used offline. The service worker caches essential application assets. Online features, such as music streaming, are disabled in offline mode but become available again once a network connection is restored.
Sources: vite.config.ts:11-47, README.md:33-36, src/App.tsx:149-151