Home

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• index.html
• src/App.tsx
• src/utils/i18n.ts
• vite.config.ts
• src/components/TerminalUI.tsx
• src/components/Pomodoro.tsx
• src/components/TaskManager.tsx
• src/index.css
• src/components/themes/BackgroundEffects.tsx
• src/components/themes/ForegroundEffects.tsx
• src/components/MikuDecorations.tsx

Endfield-Pomodoro is an immersive web-based Pomodoro application with a design inspired by Cyber UI and the game Arknights: Endfield. It integrates a configurable Pomodoro timer with a task manager and a dual-mode audio player, all wrapped in a highly stylized, themeable interface. The application is built as a Progressive Web App (PWA), enabling offline functionality and a native-like experience.

The core of the application is a single-page experience built with React. It features a main dashboard displaying the timer and other modules, and a separate settings view for comprehensive customization. All user data, including settings, tasks, and session progress, is persisted locally in the browser's localStorage.

Sources: README.md, index.html:5, src/App.tsx

Core Technologies

The project is built on a modern web technology stack, leveraging performance-oriented tools and frameworks. The React 19 Compiler is enabled to automate memoization and optimize component rendering.

Technology	Version	Purpose
React	19.2.0	Core UI library for building the user interface.
Vite	7.2.4	Build tool providing fast development server and optimized production builds.
TypeScript	~5.9.3	Superset of JavaScript that adds static typing for code robustness.
TailwindCSS	4.1.17	A utility-first CSS framework for rapid UI development and theming.
vite-plugin-pwa	1.2.0	Vite plugin for adding Progressive Web App capabilities.
react-use	17.6.0	A collection of essential React Hooks.

Sources: package.json:11-20, README.md:27-35, vite.config.ts:5-10

Application Architecture

The application is structured around a main App component that serves as the root container and state manager. It orchestrates the rendering of different views, manages global settings, and passes data down to its child components.

The overall component hierarchy is as follows:

This diagram shows the main components and how they are organized within the App component, including the conditional rendering of the Dashboard and Settings views.

Sources: src/App.tsx:238-380, README.md:63-95

View Management

The application features two primary views, controlled by the currentView state within App.tsx:

• DASHBOARD: The default view, displaying the core modules (Pomodoro, TaskManager, AudioPlayer).
• SETTINGS: A view dedicated to user configuration.

Navigation between these views is handled by buttons in the header, which update the currentView state, triggering a re-render to display the appropriate content.

Sources: src/App.tsx:49-51, src/App.tsx:308-312, src/App.tsx:382-384

State Management

State is managed locally within components using React Hooks (useState, useEffect, useRef). The top-level App.tsx component is responsible for the most critical pieces of global state.

Global State in App.tsx

• settings: An object containing all user-configurable options, such as timer durations, theme, and language.
• sessionCount: The number of completed Pomodoro work sessions.
• persistedTotalSeconds: The total accumulated study time, persisted across browser sessions.
• currentView: Determines whether the DASHBOARD or SETTINGS view is active.

Sources: src/App.tsx:61, src/App.tsx:82, src/App.tsx:88, src/App.tsx:110

Data Persistence

User data is persisted in the browser's localStorage to ensure state is maintained across page reloads and browser sessions.

The following diagram illustrates the process of loading settings when the application starts:

This persistence mechanism applies to settings, session counts, total study time, task lists, and the current timer state.

localStorage Key	Description	Source File
endfield_settings	Stores the user's configuration object (Settings).	src/App.tsx:62
endfield_sessions	Stores the count of completed Pomodoro sessions.	src/App.tsx:82
endfield_total_seconds	Stores the total focused time in seconds.	src/App.tsx:90
endfield_current_session_start	Timestamp for the start of the current work session, for accurate time tracking on refresh.	src/App.tsx:95
origin_terminal_tasks	Stores the list of tasks for the Task Manager.	src/components/TaskManager.tsx:15
endfield_timer	Stores the current state of the Pomodoro timer (mode, time left, active status).	src/components/Pomodoro.tsx:48

Sources: src/App.tsx:61-76, src/components/Pomodoro.tsx:100-115, src/components/TaskManager.tsx:14-23

Theme System

The application features a dynamic theme system that allows users to change the visual appearance instantly. This is achieved using CSS Variables.

Architecture

1. Theme Configuration: A set of predefined themes is available in src/config/themes.ts. Each theme is an object mapping CSS variable names (e.g., --color-primary) to color values.
2. State Management: The selected theme is stored in the settings.theme state within App.tsx.
3. Dynamic Application: A useLayoutEffect hook in App.tsx listens for changes to settings.theme. When the theme changes, it iterates over the new theme's color definitions and applies them to the document's root element using root.style.setProperty().
4. Component Styling: Components use TailwindCSS utility classes (e.g., bg-theme-base, text-theme-primary) which are mapped to these CSS variables in src/index.css.
5. Visual Effects: The BackgroundLayer and ForegroundLayer components, managed by TerminalUI.tsx, render different visual effects based on the selected theme, creating a more immersive experience.

The flow of applying a theme is visualized below:

Special Theming (MIKU)

The "MIKU" theme includes unique decorative elements that are not part of the standard background/foreground effect layers. The MikuDecorations component is rendered conditionally in App.tsx only when settings.theme is ThemePreset.MIKU. It positions character and logo images relative to the footer, whose height is dynamically tracked by the useFooterHeight hook.

Sources: src/App.tsx:244-245, src/components/MikuDecorations.tsx:139-145

Internationalization (i18n)

The application supports multiple languages (English and Chinese) through a simple, custom i18n implementation.

• Translations: All UI strings are stored in a translations object in src/utils/i18n.ts, organized by language code (en, cn).
• useTranslation Hook: A custom hook, useTranslation, takes the current language from the settings state and returns a function t(key). This function retrieves the appropriate string for the given key from the translations object.
• Language Detection: On first load, the application attempts to detect the user's preferred language from navigator.languages. The language can be changed at any time in the settings menu.

Sources: src/utils/i18n.ts, src/App.tsx:37-40, src/App.tsx:121

PWA (Progressive Web App) Support

The application is configured as a PWA to provide offline capabilities and allow users to "install" it on their devices. This is managed by the vite-plugin-pwa plugin.

Key PWA configurations from vite.config.ts:

• registerType: 'autoUpdate': The service worker will update automatically in the background when a new version is detected.
• manifest: Defines the application's name, icons, theme color, and other metadata for the "Add to Home Screen" experience.
• workbox Caching:
  • Static assets (js, css, png, etc.) are pre-cached.
  • Online music API calls (to api.injahow.cn) and audio files are explicitly excluded from the cache and are handled with a NetworkOnly strategy to ensure they are always fetched from the network. This is critical for PWA functionality while supporting online streaming.
  • The index.html file is configured with a NetworkFirst strategy to ensure users always get the latest version of the app shell.

Sources: vite.config.ts:11-99, README.md:42-46