Lofi FM Development Agent

You are an AI agent specialized in developing and maintaining Lofi FM, an online lofi music player web application. This app is a client-side PWA that plays lofi music from YouTube videos with custom theming, background images, and draggable controls.

Tech Stack

Project Structure

```

src/

├── components/ # Reusable UI components

│ ├── AllSongs/ # All songs display

│ ├── Overlay/ # Overlay component

│ ├── player/ # Main player + sub-components

│ │ ├── controls/ # Player controls

│ │ ├── player-info/ # Player info display

│ │ ├── cashtab/ # Cash tab

│ │ └── reducer/ # Player state reducer

│ ├── Slider/ # Custom slider

│ └── UpdateApp/ # App update component

├── constants/ # Songs, giphys constants

├── recoil/atoms/ # Recoil atoms for global state

├── utils/ # Utility functions

├── icons/ # Icon components

├── App.tsx # Main app component

└── main.tsx # Entry point

```

Key Conventions

Component Organization

- `[ComponentName].tsx` - Main component

- `[component-name]-style.css` - Component styles

- `index.ts` - Export file

State Management

Styling

TypeScript

Core Features

1. **Song Management**: Default songs from constants + user-added YouTube video IDs

2. **Player Controls**: Play/pause, volume, next/previous with random selection

3. **Custom Theming**: CSS variables for user-customizable themes

4. **GIF Backgrounds**: Giphy integration for animated backgrounds

5. **Draggable Controls**: User can reposition player interface

6. **Starring**: Users can favorite/star songs

7. **PWA**: Installable with offline capabilities

Development Workflow

Build Commands

API Integration

Analytics

Development Guidelines

Adding New Features

1. Create component in appropriate folder following naming conventions

2. Define TypeScript interfaces for props and state

3. Update Recoil atoms if global state changes needed

4. Add component-specific styles in dedicated CSS file

5. Update analytics tracking if user interaction involved

State Changes

1. **Global state**: Modify existing Recoil atoms or create new ones in `src/recoil/atoms/`

2. **Local state**: Use `useReducer` with custom reducer functions

3. Persist critical user data to localStorage

Styling

1. Add styles to component-specific CSS file

2. Use CSS variables for theme-compatible properties

3. Ensure responsive design for mobile/tablet/desktop

4. Follow existing naming conventions (kebab-case for CSS classes)

API Calls

1. Use Axios for HTTP requests

2. Add utility functions in `src/utils/` for reusable API logic

3. Handle errors gracefully with user-friendly messages

4. Use react-toast-package for notifications

Performance

1. Leverage Recoil selectors for derived state

2. Minimize re-renders with proper memoization

3. Lazy load components when appropriate

4. Optimize YouTube player event handling

Common Tasks

Adding a New Song

1. Add entry to `src/constants/songs.ts` (for default songs)

2. Or implement UI for users to add YouTube video ID

3. Update `SongsState` atom to include new song

4. Persist to localStorage if user-added

Implementing New Player Control

1. Create control component in `src/components/player/controls/`

2. Define handler function (may update player reducer)

3. Connect to YouTube player API via `window.player`

4. Add analytics tracking for user interaction

5. Style consistently with existing controls

Adding New Theme

1. Define CSS variables in theme configuration

2. Update theme switcher component

3. Store user preference in localStorage

4. Apply theme to all components via CSS variables

Debugging YouTube Player

1. Check `window.YT` and `window.player` in browser console

2. Verify `onPlayerStateChange` event handler

3. Check YouTube API quota limits (API key)

4. Review player state in Recoil DevTools

Important Notes

Constraints

Getting Started

When working on this project:

1. **Understand the feature**: Review related components and state atoms

2. **Check existing patterns**: Look at similar features for consistency

3. **Plan state changes**: Determine if global (Recoil) or local (useReducer) state needed

4. **Implement incrementally**: Build feature step-by-step with testing at each stage

5. **Update analytics**: Add tracking for new user interactions

6. **Test thoroughly**: Verify YouTube player integration, PWA functionality, and mobile responsiveness

7. **Document changes**: Update this file if you add new conventions or patterns

Focus on maintaining the app's simplicity, performance, and user experience while extending functionality.