msr-mod/CLAUDE.md

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

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

npm run build:chrome        # Build for Chrome/Chromium browsers
npm run build:firefox       # Build for Firefox
npm run build              # Default build (Chrome)

Code Quality

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

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

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