Astrian Zheng
5be5b4812f
- 添加项目使用 Tab 缩进的说明 - 添加随机播放模式的详细逻辑说明 - 说明 shuffleList 和 currentIndex 的关系 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
130 lines
5.1 KiB
Markdown
130 lines
5.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
MSR Mod is a browser extension that provides an alternate frontend for Monster Siren Records (monster-siren.hypergryph.com). It's built with Vue 3, TypeScript, and Tailwind CSS, designed to work as both Chrome and Firefox extensions.
|
|
|
|
## Common Commands
|
|
|
|
### Development
|
|
```bash
|
|
npm run dev # Start development server with Vite
|
|
npm run dev:refresh # Build and refresh dist folder for extension development
|
|
npm i # Install dependencies
|
|
```
|
|
|
|
### Building
|
|
```bash
|
|
npm run build:chrome # Build for Chrome/Chromium browsers
|
|
npm run build:firefox # Build for Firefox
|
|
npm run build # Default build (Chrome)
|
|
```
|
|
|
|
### Code Quality
|
|
```bash
|
|
npm run lint # Format code with Biome
|
|
npm run quality-check # Run Biome CI checks
|
|
npm run qc # Alias for quality-check
|
|
```
|
|
|
|
### Extension Development Workflow
|
|
1. Run `npm run dev:refresh` to build initial dist folder
|
|
2. Load the `dist` folder as an unpacked extension in browser
|
|
3. Use `npm run dev` for hot-reload development
|
|
4. Use `npm run build:watch` for continuous builds
|
|
|
|
## Architecture
|
|
|
|
### Core Technologies
|
|
- **Vue 3** with Composition API and `<script setup>` syntax
|
|
- **TypeScript** for type safety
|
|
- **Pinia** for state management
|
|
- **Vue Router** with hash history for extension compatibility
|
|
- **Tailwind CSS v4** for styling
|
|
- **GSAP** for animations
|
|
- **Axios** for API communication
|
|
|
|
### Browser Extension Structure
|
|
- **Manifest V3** with platform-specific builds
|
|
- **Content Scripts** inject the frontend on monster-siren.hypergryph.com
|
|
- **Background Service Worker** handles extension lifecycle
|
|
- **Cross-platform compatibility** via prebuild scripts
|
|
|
|
### State Management (Pinia Stores)
|
|
- **usePlayQueueStore**: Music playback queue, shuffle/repeat modes, audio preloading
|
|
- **useFavourites**: User favorites with cross-platform storage (Chrome storage API/localStorage)
|
|
- **usePreferences**: User settings and preferences
|
|
|
|
### Key Components
|
|
- **Player**: Main audio player with preloading and resource validation
|
|
- **Playroom**: Full-screen player interface with lyrics and visualizations
|
|
- **ScrollingLyrics**: Animated lyrics display with auto-scroll and user interaction
|
|
- **PlayListItem/TrackItem**: Reusable music track components
|
|
|
|
### API Integration
|
|
- **Monster Siren API**: Fetches songs, albums, and metadata via `src/apis/index.ts`
|
|
- **Resource URL Validation**: Automatic refresh of cached URLs when servers rotate resources
|
|
- **Preloading System**: Smart audio preloading with cache management
|
|
|
|
### Browser Compatibility
|
|
- **Chrome**: Uses service worker, full CSP support
|
|
- **Firefox**: Uses background scripts, modified CSP, specific gecko settings
|
|
- **Prebuild Scripts**: Automatically modify manifest.json and HTML for each platform
|
|
|
|
### Storage Strategy
|
|
- **Favorites**: Stored in Chrome storage API (fallback to localStorage)
|
|
- **Preferences**: Browser-specific storage with graceful degradation
|
|
- **Audio Cache**: In-memory preloading with size limits
|
|
|
|
### Resource Management
|
|
- **Audio Preloading**: Validates and preloads next track during playback
|
|
- **URL Refresh Logic**: Checks resource availability before playback/preload
|
|
- **Cache Invalidation**: Automatic cleanup when resource URLs change
|
|
|
|
### Shuffle/Random Play Logic
|
|
- **shuffleList**: Array storing the shuffled order of original list indices
|
|
- **currentIndex**: In shuffle mode, this is the index within shuffleList
|
|
- **Accessing current song**: `list[shuffleList[currentIndex]]` in shuffle mode
|
|
- **getNextIndex**: Returns the actual list index of the next song to play
|
|
|
|
## File Structure Notes
|
|
|
|
### `/src/utils/`
|
|
- **songResourceChecker.ts**: Centralized resource validation and refresh logic
|
|
- **audioVisualizer.ts**: Real-time audio analysis for visual effects
|
|
- **artistsOrganize.ts**: Helper for formatting artist names
|
|
|
|
### `/scripts/`
|
|
- **prebuild-chrome.js**: Removes localhost dev configs for production
|
|
- **prebuild-firefox.js**: Adapts manifest for Firefox compatibility
|
|
|
|
### `/public/`
|
|
- **manifest.json**: Extension manifest (modified by prebuild scripts)
|
|
- **content.js**: Injects the Vue app into target websites
|
|
- **background.js**: Extension background script
|
|
|
|
## Code Style and Formatting
|
|
|
|
### Indentation
|
|
- **This project uses Tab indentation (not spaces)**
|
|
- Ensure all code edits maintain consistent Tab indentation
|
|
- When editing files, preserve the existing Tab character formatting
|
|
|
|
## Development Considerations
|
|
|
|
### Extension Context
|
|
- Uses hash routing for browser extension compatibility
|
|
- CSP restrictions require specific script and style handling
|
|
- Cross-origin requests limited to declared host permissions
|
|
|
|
### Performance
|
|
- Audio preloading system prevents playback interruptions
|
|
- Resource validation happens only when needed (playback/preload)
|
|
- GSAP animations with proper cleanup to prevent memory leaks
|
|
|
|
### Error Handling
|
|
- Graceful fallbacks for storage API unavailability
|
|
- Resource URL rotation handling with automatic refresh
|
|
- Cross-browser compatibility with feature detection |