docs: add CLAUDE.md for future Claude Code instances

Create comprehensive documentation covering project architecture,
development commands, and browser extension specifics to help
future Claude Code instances work effectively in this codebase.

Includes coverage of Vue 3 + TypeScript setup, Pinia state management,
cross-browser extension building, audio preloading system, and
resource URL validation architecture.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,117 @@
+# 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
+
+## 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