chore: bump app to v4.2.2

- Embed DownloadQueueLookup into DownloadQueueState; add updatedForIndices() for O(changed) incremental updates during frequent progress ticks instead of full O(n) rebuild
- downloadQueueLookupProvider now reads pre-computed lookup from state directly
- Replace sync file deletion in DownloadedEmbeddedCoverResolver with unawaited async cleanup to avoid blocking the main thread
- Parse JSON payloads on iOS native side (parseJsonPayload) so event sinks and method channel responses return native objects, avoiding redundant Dart-side JSON decode
- Use .cast<String, dynamic>() instead of Map.from() in _decodeMapResult for zero-copy map handling

.fvmrc

@@ -0,0 +1,3 @@
+{
+  "flutter": "3.41.5"
+}

.gitattributes

@@ -0,0 +1,20 @@
+* text=auto eol=lf
+
+# Windows scripts
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+# Binary files
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.webp binary
+*.ico binary
+*.pdf binary
+*.zip binary
+*.jar binary
+*.aar binary
+*.keystore binary
+*.jks binary

.github/FUNDING.yml

@@ -1,4 +1,3 @@
 github: zarzet
 ko_fi: zarzet
-buy_me_a_coffee: zarzet
 

.github/ISSUE_TEMPLATE/config.yml

@@ -4,5 +4,5 @@ contact_links:
     url: https://github.com/zarzet/SpotiFLAC-Mobile#readme
     about: Check the README for setup instructions and FAQ
   - name: Extension Development Guide
-    url: https://zarz.moe/docs
+    url: https://spotiflac.zarz.moe/docs
     about: Documentation for building SpotiFLAC extensions

.github/workflows/auto-tag.yml

@@ -15,7 +15,7 @@ jobs:
     
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 2  # Need previous commit to compare
 

.github/workflows/pages.yml

@@ -0,0 +1,44 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release.yml

@@ -60,23 +60,23 @@ jobs:
           df -h
 
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Java
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           distribution: "temurin"
           java-version: "17"
 
       - name: Setup Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
-          go-version: "1.21"
+          go-version: "1.25.8"
           cache-dependency-path: go_backend/go.sum
 
       # Cache Gradle for faster builds
       - name: Cache Gradle
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: |
             ~/.gradle/caches
@@ -93,12 +93,12 @@ jobs:
           # Accept licenses
           yes | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses || true
 
-          # Install NDK r27d LTS (required for 16KB page size support on Android 15+)
+          # Install NDK r29 (supports 16KB page size for Android 15+)
           # Platform android-36 and build-tools 36.0.0 for targetSdk 36 (Android 16)
-          $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager "ndk;27.3.13750724" "platforms;android-36" "build-tools;36.0.0"
+          $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager "ndk;29.0.14206865" "platforms;android-36" "build-tools;36.0.0"
 
           # Set NDK path
-          echo "ANDROID_NDK_HOME=$ANDROID_HOME/ndk/27.3.13750724" >> $GITHUB_ENV
+          echo "ANDROID_NDK_HOME=$ANDROID_HOME/ndk/29.0.14206865" >> $GITHUB_ENV
 
       - name: Install gomobile
         run: |
@@ -158,28 +158,33 @@ jobs:
           ls -la
 
       - name: Upload APK artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: android-apk
           path: build/app/outputs/flutter-apk/SpotiFLAC-*.apk
 
   build-ios:
-    runs-on: macos-latest
+    runs-on: macos-15
     needs: get-version # Only depends on version, NOT android build!
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+
+      - name: Select Xcode 26.1.1
+        run: |
+          sudo xcode-select -s /Applications/Xcode_26.1.1.app
+          xcodebuild -version
 
       - name: Setup Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
-          go-version: "1.21"
+          go-version: "1.25.8"
           cache-dependency-path: go_backend/go.sum
 
       # Cache CocoaPods
       - name: Cache CocoaPods
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ios/Pods
           key: pods-${{ runner.os }}-${{ hashFiles('ios/Podfile.lock') }}
@@ -194,7 +199,7 @@ jobs:
         working-directory: go_backend
         run: |
           mkdir -p ../ios/Frameworks
-          gomobile bind -target=ios -o ../ios/Frameworks/Gobackend.xcframework .
+          gomobile bind -target=ios -tags ios -o ../ios/Frameworks/Gobackend.xcframework .
         env:
           CGO_ENABLED: 1
 
@@ -249,23 +254,6 @@ jobs:
           channel: "stable"
           cache: true
 
-      # Swap pubspec for iOS build (includes ffmpeg_kit_flutter)
-      - name: Use iOS pubspec with FFmpeg plugin
-        run: |
-          cp pubspec.yaml pubspec_android_backup.yaml
-          cp pubspec_ios.yaml pubspec.yaml
-          echo "Swapped to iOS pubspec with ffmpeg_kit_flutter"
-
-      # Swap FFmpeg service for iOS
-      - name: Use iOS FFmpeg service
-        run: |
-          cp lib/services/ffmpeg_service.dart lib/services/ffmpeg_service_android.dart
-          cp build_assets/ffmpeg_service_ios.dart lib/services/ffmpeg_service.dart
-          # Update class name in the swapped file
-          sed -i '' 's/FFmpegServiceIOS/FFmpegService/g' lib/services/ffmpeg_service.dart
-          sed -i '' 's/FFmpegResultIOS/FFmpegResult/g' lib/services/ffmpeg_service.dart
-          echo "Swapped to iOS FFmpeg service"
-
       - name: Get Flutter dependencies
         run: flutter pub get
 
@@ -312,7 +300,7 @@ jobs:
           fi
 
       - name: Upload IPA artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: ios-ipa
           path: build/ios/ipa/SpotiFLAC-*.ipa
@@ -325,43 +313,33 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # Full history needed for git-cliff
 
-      - name: Extract changelog for version
+      - name: Generate changelog with git-cliff
         id: changelog
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: cliff.toml
+          args: --latest --strip header
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          OUTPUT: /tmp/changelog.txt
+
+      - name: Show generated changelog
         run: |
-          VERSION=${{ needs.get-version.outputs.version }}
-          VERSION_NUM=${VERSION#v}  # Remove 'v' prefix
-
-          echo "Looking for version: $VERSION_NUM"
-
-          # Extract changelog section for this version using sed
-          # Find the line with version, then print until next version header or end
-          CHANGELOG=$(sed -n "/^## \[$VERSION_NUM\]/,/^## \[/{ /^## \[$VERSION_NUM\]/d; /^## \[/d; p; }" CHANGELOG.md)
-
-          # If no changelog found, use default message
-          if [ -z "$CHANGELOG" ]; then
-            echo "No changelog found for version $VERSION_NUM"
-            CHANGELOG="See CHANGELOG.md for details."
-          else
-            echo "Found changelog content"
-            # Remove trailing --- separator if present (CHANGELOG uses --- between versions)
-            CHANGELOG=$(echo "$CHANGELOG" | sed '/^---$/d')
-          fi
-
-          # Save to file for multiline support
-          echo "$CHANGELOG" > /tmp/changelog.txt
-          echo "Extracted changelog:"
+          echo "Generated changelog:"
           cat /tmp/changelog.txt
 
       - name: Download Android APK
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
         with:
           name: android-apk
           path: ./release
 
       - name: Download iOS IPA
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
         with:
           name: ios-ipa
           path: ./release
@@ -369,15 +347,22 @@ jobs:
       - name: Prepare release body
         run: |
           VERSION=${{ needs.get-version.outputs.version }}
-          cat > /tmp/release_body.txt << 'HEADER'
-          ### What's New
-          HEADER
-
-          cat /tmp/changelog.txt >> /tmp/release_body.txt
-
           REPO_OWNER="${{ github.repository_owner }}"
           REPO_NAME="${{ github.event.repository.name }}"
-          
+          CURRENT_REF=$(git rev-list -n 1 "$VERSION" 2>/dev/null || git rev-parse HEAD)
+          PREVIOUS_TAG=$(git describe --tags --abbrev=0 "${CURRENT_REF}^" 2>/dev/null || true)
+
+          # Start with git-cliff changelog, but replace its compare footer with a
+          # deterministic previous-tag lookup from git.
+          sed '/^## [0-9][0-9.[:alpha:]-]*$/d; /^\*\*Full Changelog\*\*/d' /tmp/changelog.txt > /tmp/release_body.txt
+
+          if [ -n "$PREVIOUS_TAG" ]; then
+            printf '\n**Full Changelog**: [%s...%s](https://github.com/%s/%s/compare/%s...%s)\n' \
+              "$PREVIOUS_TAG" "$VERSION" "$REPO_OWNER" "$REPO_NAME" "$PREVIOUS_TAG" "$VERSION" \
+              >> /tmp/release_body.txt
+          fi
+
+          # Append download section
           cat >> /tmp/release_body.txt << FOOTER
 
           ---
@@ -402,7 +387,7 @@ jobs:
           cat /tmp/release_body.txt
 
       - name: Create Release
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ needs.get-version.outputs.version }}
           name: SpotiFLAC ${{ needs.get-version.outputs.version }}
@@ -413,6 +398,63 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  update-altstore:
+    runs-on: ubuntu-latest
+    needs: [get-version, build-ios, create-release]
+    if: ${{ needs.get-version.outputs.is_prerelease != 'true' }}
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout main branch
+        uses: actions/checkout@v6
+        with:
+          ref: main
+
+      - name: Download iOS IPA
+        uses: actions/download-artifact@v7
+        with:
+          name: ios-ipa
+          path: ./release
+
+      - name: Update apps.json
+        run: |
+          VERSION="${{ needs.get-version.outputs.version }}"
+          VERSION_NUM="${VERSION#v}"
+          DATE=$(date -u +%Y-%m-%d)
+          IPA_FILE=$(find ./release -name "*ios*.ipa" | head -1)
+
+          if [ -z "$IPA_FILE" ]; then
+            echo "WARNING: IPA file not found, skipping apps.json update"
+            exit 0
+          fi
+
+          IPA_SIZE=$(stat -c%s "$IPA_FILE" 2>/dev/null || stat -f%z "$IPA_FILE")
+
+          if [ ! -f apps.json ]; then
+            echo "WARNING: apps.json not found on main, skipping"
+            exit 0
+          fi
+
+          jq --arg ver "$VERSION_NUM" \
+             --arg date "$DATE" \
+             --arg url "https://github.com/zarzet/SpotiFLAC-Mobile/releases/download/${VERSION}/SpotiFLAC-${VERSION}-ios-unsigned.ipa" \
+             --argjson size "$IPA_SIZE" \
+             '.apps[0].version = $ver | .apps[0].versionDate = $date | .apps[0].downloadURL = $url | .apps[0].size = $size' \
+             apps.json > apps.json.tmp && mv apps.json.tmp apps.json
+
+          echo "Updated apps.json:"
+          cat apps.json
+
+      - name: Commit and push
+        run: |
+          VERSION="${{ needs.get-version.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add apps.json
+          git diff --cached --quiet && echo "No changes to commit" || \
+            (git commit -m "chore: update AltStore source to ${VERSION}" && git push)
+
   notify-telegram:
     runs-on: ubuntu-latest
     needs: [get-version, create-release]
@@ -420,59 +462,60 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - name: Download Android APK
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
         with:
           name: android-apk
           path: ./release
 
       - name: Download iOS IPA
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
         with:
           name: ios-ipa
           path: ./release
 
-      - name: Extract changelog for version
+      - name: Generate changelog with git-cliff for Telegram
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: cliff.toml
+          args: --latest --strip all
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          OUTPUT: /tmp/cliff_tg.txt
+
+      - name: Convert changelog for Telegram
         id: changelog
         run: |
-          VERSION=${{ needs.get-version.outputs.version }}
-          VERSION_NUM=${VERSION#v}
-
-          # Extract changelog, limit to ~2500 chars for Telegram (4096 limit minus message overhead)
-          FULL_CHANGELOG=$(sed -n "/^## \[$VERSION_NUM\]/,/^## \[/{ /^## \[$VERSION_NUM\]/d; /^## \[/d; p; }" CHANGELOG.md | sed '/^---$/d')
-          
-          if [ -z "$FULL_CHANGELOG" ]; then
-            CHANGELOG="See release notes on GitHub for details."
+          if [ ! -s /tmp/cliff_tg.txt ]; then
+            echo "See release notes on GitHub for details." > /tmp/changelog.txt
           else
-            # Convert GitHub Markdown to Telegram HTML:
-            # - **text** → <b>text</b>
-            # - `code` → <code>code</code>
-            # - ### Header → <b>Header</b>
-            # - Escape HTML special chars first
-            CHANGELOG=$(echo "$FULL_CHANGELOG" | \
+            # Convert Markdown to Telegram HTML
+            CHANGELOG=$(cat /tmp/cliff_tg.txt | \
+              sed '/^## [0-9][0-9.[:alpha:]-]*$/d' | \
+              sed '/^\*\*Full Changelog\*\*/d' | \
+              sed 's/ by \[@[^]]*\](https:\/\/github\.com\/[^)]*)//g' | \
+              sed 's/ by @[A-Za-z0-9_-]\+//g' | \
+              sed 's/\[#\([0-9]*\)\]([^)]*)/#\1/g' | \
+              sed 's/\[@\([^]]*\)\]([^)]*)/@\1/g' | \
               sed 's/&/\&amp;/g' | \
               sed 's/</\&lt;/g' | \
               sed 's/>/\&gt;/g' | \
-              sed 's/`\([^`]*\)`/<code>\1<\/code>/g' | \
               sed 's/\*\*\([^*]*\)\*\*/<b>\1<\/b>/g' | \
               sed 's/^### \(.*\)$/<b>\1<\/b>/g' | \
               sed 's/^## \(.*\)$/<b>\1<\/b>/g' | \
-              sed 's/^- /• /g' | \
-              sed 's/^  - /  ◦ /g')
-            
-            # Take first 2500 characters, then cut at last complete line
+              sed 's/^- /• /g')
+
+            # Truncate for Telegram 4096 char limit
             CHANGELOG=$(echo "$CHANGELOG" | head -c 2500 | sed '$d')
-            
-            # Check if truncated
-            FULL_LEN=${#FULL_CHANGELOG}
-            if [ $FULL_LEN -gt 2500 ]; then
-              CHANGELOG="${CHANGELOG}"$'\n\n... (see full changelog on GitHub)'
-            fi
+            echo "$CHANGELOG" > /tmp/changelog.txt
           fi
 
-          echo "$CHANGELOG" > /tmp/changelog.txt
+          echo "Telegram changelog:"
+          cat /tmp/changelog.txt
 
       - name: Send to Telegram Channel
         env:
@@ -499,11 +542,13 @@ jobs:
           MESSAGE=$(cat /tmp/telegram_message.txt)
 
           # Send message first (using HTML parse mode)
+          # Use --data-urlencode for proper encoding of special chars (+, &, etc.)
+          # Use || true to ensure file uploads continue even if message fails
           curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
-            -d chat_id="${TELEGRAM_CHANNEL_ID}" \
-            -d text="${MESSAGE}" \
-            -d parse_mode="HTML" \
-            -d disable_web_page_preview="true"
+            --data-urlencode "chat_id=${TELEGRAM_CHANNEL_ID}" \
+            --data-urlencode "text=${MESSAGE}" \
+            --data-urlencode "parse_mode=HTML" \
+            --data-urlencode "disable_web_page_preview=true" || true
 
           # Upload arm64 APK to channel
           if [ -f "$ARM64_APK" ]; then

.gitignore

@@ -12,6 +12,9 @@ Thumbs.db
 # Kiro specs (development only)
 .kiro/
 
+# Design assets (banners, mockups)
+design/
+
 # Reference folder (development only)
 referensi/
 
@@ -64,6 +67,7 @@ AGENTS.md
 
 # Temp/misc
 nul
+network_requests.txt
 
 # Log files
 *.log
@@ -72,3 +76,8 @@ flutter_*.log
 
 # Development tools
 tool/
+.claude/settings.local.json
+.playwright-mcp/
+
+# FVM Version Cache
+.fvm/

CONTRIBUTING.md

@@ -86,17 +86,31 @@ Translation files are located in `lib/l10n/arb/`.
    git remote add upstream https://github.com/zarzet/SpotiFLAC-Mobile.git
    ```
 
-3. **Install dependencies**
+3. **Use FVM (Flutter Version: 3.38.1)**
+   ```bash
+   fvm use
+   ```
+
+4. **Install dependencies**
    ```bash
    flutter pub get
    ```
 
-4. **Generate code** (for Riverpod, JSON serialization, etc.)
+5. **Generate code** (for Riverpod, JSON serialization, etc.)
    ```bash
    dart run build_runner build --delete-conflicting-outputs
    ```
 
-5. **Run the app**
+6. **Set up Go environment (Go Version: 1.25.7)**
+   ```bash
+   cd go_backend 
+   mkdir -p ../android/app/libs
+   gomobile init
+   gomobile bind -target=android -androidapi 24 -o ../android/app/libs/gobackend.aar .
+   cd ..
+   ```
+
+7. **Run the app**
    ```bash
    flutter run
    ```

README.md

@@ -1,19 +1,29 @@
-[![GitHub All Releases](https://img.shields.io/github/downloads/zarzet/SpotiFLAC-Mobile/total?style=for-the-badge)](https://github.com/zarzet/SpotiFLAC-Mobile/releases)
-[![VirusTotal](https://img.shields.io/badge/VirusTotal-Safe-brightgreen?style=for-the-badge&logo=virustotal)](https://www.virustotal.com/gui/file/3257155286587a3596ad5d4380d4576a684aa3d37a5b19a615914a845fbe57f3)
-[![Crowdin](https://img.shields.io/badge/HELP%20TRANSLATE%20ON-CROWDIN-%2321252b?style=for-the-badge&logo=crowdin)](https://crowdin.com/project/spotiflac-mobile)
-
 <div align="center">
 
-<img src="icon.png" width="128" />
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/images/banner-readme-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="assets/images/banner-readme-light.png">
+  <img alt="SpotiFLAC Mobile" src="assets/images/banner-readme-light.png" width="650" height="auto">
+</picture>
 
-Download music in true lossless FLAC from Tidal, Qobuz & Amazon Music — no account required.
-
-![Android](https://img.shields.io/badge/Android-7.0%2B-3DDC84?style=for-the-badge&logo=android&logoColor=white)
-![iOS](https://img.shields.io/badge/iOS-14.0%2B-000000?style=for-the-badge&logo=apple&logoColor=white)
+<p align="center">
+  <a href="https://trendshift.io/repositories/17247">
+    <img src="https://trendshift.io/api/badge/repositories/17247" alt="zarzet%2FSpotiFLAC-Mobile | Trendshift" width="250" height="55">
+  </a>
+</p>
 
 </div>
 
-### [Download](https://github.com/zarzet/SpotiFLAC-Mobile/releases)
+<div align="center">
+
+[![GitHub Release](https://img.shields.io/github/v/release/zarzet/SpotiFLAC-Mobile?style=for-the-badge&logo=github)](https://github.com/zarzet/SpotiFLAC-Mobile/releases)
+[![VirusTotal](https://img.shields.io/badge/VirusTotal-Safe-brightgreen?style=for-the-badge&logo=virustotal)](https://www.virustotal.com/gui/file/31d1bf3c3b2015c13e83c4f909a7c6093a9423e3e702f0c582a3e0035c849424)
+[![Crowdin](https://img.shields.io/badge/HELP%20TRANSLATE%20ON-CROWDIN-%2321252b?style=for-the-badge&logo=crowdin)](https://crowdin.com/project/spotiflac-mobile)
+
+[![Telegram Channel](https://img.shields.io/badge/CHANNEL-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/spotiflac)
+[![Telegram Community](https://img.shields.io/badge/COMMUNITY-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/spotiflac_chat)
+
+</div>
 
 ## Screenshots
 
@@ -24,79 +34,154 @@ Download music in true lossless FLAC from Tidal, Qobuz & Amazon Music — no acc
   <img src="assets/images/4.jpg?v=2" width="200" />
 </p>
 
-## Search Source
-
-SpotiFLAC supports multiple search sources for finding music metadata:
-
-| Source | Setup |
-|--------|-------|
-| **Deezer** (Default) | No setup required |
-| **Extensions** | Install additional search providers from the Store |
+---
 
 ## Extensions
 
-Extensions allow the community to add new music sources and features without waiting for app updates. When a streaming service API changes or a new source becomes available, extensions can be updated independently.
+Extensions let the community add new music sources and features without waiting for app updates. When a streaming service API changes or a new source becomes available, extensions can be updated independently.
 
 ### Installing Extensions
-1. Go to **Store** tab in the app
-2. Browse and install extensions with one tap
-3. Or download a `.spotiflac-ext` file and install manually via **Settings > Extensions**
-4. Configure extension settings if needed
-5. Set provider priority in **Settings > Extensions > Provider Priority**
+
+1. Open the **Store** tab in the app
+2. On first launch, enter an **Extension Repository URL** when prompted
+3. Browse and install extensions with one tap
+4. Or download a `.spotiflac-ext` file and install manually via **Settings > Extensions**
+5. Configure extension settings if needed
+6. Set provider priority under **Settings > Extensions > Provider Priority**
 
 ### Developing Extensions
-Want to create your own extension? Check out the [Extension Development Guide](https://zarz.moe/docs) for complete documentation.
 
-## Other project
+> [!NOTE]
+> Want to build your own extension? The [Extension Development Guide](https://zarzet.github.io/SpotiFLAC-Mobile/docs) has everything you need.
+
+---
+
+## Related Projects
 
 ### [SpotiFLAC (Desktop)](https://github.com/afkarxyz/SpotiFLAC)
-Download music in true lossless FLAC from Tidal, Qobuz & Amazon Music for Windows, macOS & Linux
+Download music in true lossless FLAC from Tidal, Qobuz & Amazon Music available for Windows, macOS & Linux.
 
-> **Note:** Currently unavailable because the GitHub account is suspended. Alternatively, use [SpotiFLAC-Next](https://github.com/spotiverse/SpotiFLAC-Next) until the original is restored.
+### [SpotiFLAC (Python Module)](https://github.com/ShuShuzinhuu/SpotiFLAC-Module-Version)
+Python library for SpotiFLAC integration, maintained by [@ShuShuzinhuu](https://github.com/ShuShuzinhuu).
 
-## Telegram
-
-<p align="center">
-  <a href="https://t.me/spotiflac">
-    <img src="https://img.shields.io/badge/Telegram-Channel-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white" alt="Telegram Channel">
-  </a>
-
-  <a href="https://t.me/spotiflacchat">
-    <img src="https://img.shields.io/badge/Telegram-Community-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white" alt="Telegram Community">
-  </a>
-</p>
+---
 
 ## FAQ
 
-**Q: Why is my download failing with "Song not found"?**  
-A: The track may not be available on Tidal, Qobuz, or Amazon Music. Try enabling more download services in Settings > Download > Provider Priority, or install additional extensions from the Store.
+<details>
+<summary><b>Why does the Store tab ask me to enter a URL?</b></summary>
+<br>
 
-**Q: Why are some tracks downloading in lower quality?**  
-A: Quality depends on what's available from the streaming service. Tidal offers up to 24-bit/192kHz, Qobuz up to 24-bit/192kHz, and Amazon up to 24-bit/48kHz. The app automatically selects the best available quality.
+Starting from version 3.8.0, SpotiFLAC uses a decentralized extension repository system extensions are hosted on GitHub repositories rather than a built-in server, so anyone can create and host their own. Enter a repository URL in the Store tab to browse and install extensions.
 
-**Q: Can I download playlists?**  
-A: Yes! Just paste the playlist URL in the search bar. The app will fetch all tracks and queue them for download.
+</details>
 
-**Q: Why do I need to grant storage permission?**  
-A: The app needs permission to save downloaded files to your device. On Android 13+, you may need to grant "All files access" in Settings > Apps > SpotiFLAC > Permissions.
+<details>
+<summary><b>Why is my download failing with "Song not found"?</b></summary>
+<br>
 
-**Q: Is this app safe?**  
-A: Yes, the app is open source and you can verify the code yourself. Each release is scanned with VirusTotal (see badge at top of README).
+The track may not be available on the streaming services. Try enabling more providers under **Settings > Download > Provider Priority**, or install additional extensions like Amazon Music from the Store.
 
-**Q: Why is download not working in my country?**  
-A: Some countries have restricted access to certain streaming service APIs. If downloads are failing, try using a VPN to connect through a different region.
+</details>
+
+<details>
+<summary><b>Why are some tracks downloading in lower quality?</b></summary>
+<br>
+
+Quality depends on what's available from the streaming service and its extensions. Built-in providers:
+- **Tidal** up to 24-bit/192kHz
+- **Qobuz** up to 24-bit/192kHz
+- **Deezer** up to 16-bit/44.1kHz
+
+</details>
+
+<details>
+<summary><b>Can I download playlists?</b></summary>
+<br>
+
+Yes! Just paste the playlist URL in the search bar. The app will fetch all tracks and queue them for download.
+
+</details>
+
+<details>
+<summary><b>Why do I need to grant storage permission?</b></summary>
+<br>
+
+The app needs permission to save downloaded files to your device. On Android 13+, you may need to grant **All files access** under **Settings > Apps > SpotiFLAC > Permissions**.
+
+</details>
+
+<details>
+<summary><b>Is this app safe?</b></summary>
+<br>
+
+Yes SpotiFLAC is open source and you can verify the code yourself. Each release is also scanned with VirusTotal (see badge above).
+
+</details>
+
+<details>
+<summary><b>Why is downloading not working in my country?</b></summary>
+<br>
+
+Some countries have restricted access to certain streaming service APIs. If downloads are failing, try using a VPN to connect through a different region.
+
+</details>
+
+<details>
+<summary><b>Can I add SpotiFLAC to AltStore or SideStore?</b></summary>
+<br>
+
+Yes! Add the official source to receive updates directly within the app. Copy this link:
+
+```
+https://raw.githubusercontent.com/zarzet/SpotiFLAC-Mobile/refs/heads/main/apps.json
+```
+
+In AltStore/SideStore, go to **Browse > Sources**, tap **+**, and paste the link.
+
+</details>
+
+> [!NOTE]
+> If SpotiFLAC is useful to you, consider supporting development:
+>
+> [![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/zarzet)
+
+---
+
+## Contributors
+
+Thanks to everyone who has contributed to SpotiFLAC Mobile!
+
+<a href="https://github.com/zarzet/SpotiFLAC-Mobile/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=zarzet/SpotiFLAC-Mobile" />
+</a>
+
+We also appreciate everyone who helped with [translations on Crowdin](https://crowdin.com/project/spotiflac-mobile), reported bugs, suggested features, and spread the word.
+
+Interested in contributing? Check out the [Contributing Guide](CONTRIBUTING.md) to get started!
+
+---
+
+## API Credits
+
+| | | | | |
+|---|---|---|---|---|
+| [hifi-api](https://github.com/binimum/hifi-api) | [music.binimum.org](https://music.binimum.org) | [qqdl.site](https://qqdl.site) | [squid.wtf](https://squid.wtf) | [spotisaver.net](https://spotisaver.net) |
+| [dabmusic.xyz](https://dabmusic.xyz) | [AfkarXYZ](https://github.com/afkarxyz) | [LRCLib](https://lrclib.net) | [Paxsenix](https://lyrics.paxsenix.org) | [Cobalt](https://cobalt.tools) |
+| [qwkuns.me](https://qwkuns.me) | [SpotubeDL](https://spotubedl.com) | [Song.link](https://song.link) | [IDHS](https://github.com/sjdonado/idonthavespotify) | |
+
+---
 
 ## Disclaimer
 
-This project is for **educational and private use only**. The developer does not condone or encourage copyright infringement.
+This repository and its contents are provided strictly for educational and research purposes. The software is provided "as-is" without warranty of any kind, express or implied, as stated in the [MIT License](LICENSE).
 
-**SpotiFLAC** is a third-party tool and is not affiliated with, endorsed by, or connected to Tidal, Qobuz, Amazon Music, Deezer, or any other streaming service.
+- No copyrighted content is hosted, stored, mirrored, or distributed by this repository.
+- Users must ensure that their use of this software is properly authorized and complies with all applicable laws, regulations, and third-party terms of service.
+- This software is provided free of charge by the maintainer. If you paid a third party for access to this software in its original form from this repository, you may have been misled or scammed. Any redistribution or commercial use by third parties must comply with the terms of the repository license. No affiliation, endorsement, or support by the maintainer is implied unless explicitly stated in writing.
+- SpotiFLAC Mobile is an independent project. It is not affiliated with, endorsed by, or connected to any other project or version on other platforms that may share a similar name. The maintainer of this repository has no control over or responsibility for third-party projects.
+- The author(s) disclaim all liability for any direct, indirect, incidental, or consequential damages arising from the use or misuse of this software. Users assume all risk associated with its use.
+- If you are a copyright holder or authorized representative and believe this repository infringes upon your rights, please contact the maintainer with sufficient detail (including relevant URLs and proof of ownership). The matter will be promptly investigated and appropriate action will be taken, which may include removal of the referenced material.
 
-The application is purely a user interface that facilitates communication between your device and existing third-party services.
-
-You are solely responsible for:
-1. Ensuring your use of this software complies with your local laws.
-2. Reading and adhering to the Terms of Service of the respective platforms.
-3. Any legal consequences resulting from the misuse of this tool.
-
-The software is provided "as is", without warranty of any kind. The author assumes no liability for any bans, damages, or legal issues arising from its use.
+> [!TIP]
+> **Star the repo** to get notified about all new releases directly from GitHub.

analysis_options.yaml

@@ -9,6 +9,19 @@
 # packages, and plugins designed to encourage good coding practices.
 include: package:flutter_lints/flutter.yaml
 
+analyzer:
+  exclude:
+    - build/**
+    - .dart_tool/**
+    - lib/**/*.g.dart
+    - lib/l10n/*.dart
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+  plugins:
+    - custom_lint
+
 linter:
   # The lint rules applied to this project can be customized in the
   # section below to disable rules from the `package:flutter_lints/flutter.yaml`
@@ -23,6 +36,13 @@ linter:
   rules:
     # avoid_print: false  # Uncomment to disable the `avoid_print` rule
     # prefer_single_quotes: true  # Uncomment to enable the `prefer_single_quotes` rule
+    avoid_dynamic_calls: true
+    cancel_subscriptions: true
+    close_sinks: true
+
+custom_lint:
+  rules:
+    - avoid_public_notifier_properties
 
 # Additional information about this file can be found at
 # https://dart.dev/guides/language/analysis-options

android/app/build.gradle.kts

@@ -57,6 +57,18 @@ android {
     }
 
     buildTypes {
+        getByName("debug") {
+            ndk {
+                debugSymbolLevel = "FULL"
+            }
+        }
+
+        getByName("profile") {
+            ndk {
+                debugSymbolLevel = "FULL"
+            }
+        }
+
         release {
             // For local builds: use release signing if key.properties exists
             // For CI builds: APK is signed by GitHub Action after build
@@ -71,6 +83,9 @@ android {
                 getDefaultProguardFile("proguard-android-optimize.txt"),
                 "proguard-rules.pro"
             )
+            ndk {
+                debugSymbolLevel = "FULL"
+            }
         }
     }
     
@@ -96,11 +111,13 @@ repositories {
 }
 
 dependencies {
-    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
+    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
     
     // Include all AAR and JAR files from libs folder
     implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar", "*.aar"))))
     
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
-    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2")
+    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.10.0")
+    implementation("androidx.documentfile:documentfile:1.1.0")
+    implementation("androidx.activity:activity-ktx:1.12.3")
 }

android/app/proguard-rules.pro

@@ -5,6 +5,7 @@
 -keep class io.flutter.view.** { *; }
 -keep class io.flutter.** { *; }
 -keep class io.flutter.plugins.** { *; }
+-keep class io.flutter.embedding.** { *; }
 
 # Ignore missing Play Core classes (not used, but referenced by Flutter)
 -dontwarn com.google.android.play.core.splitcompat.**
@@ -14,13 +15,22 @@
 # Ignore missing javax.xml.stream (not used on Android)
 -dontwarn javax.xml.stream.**
 
-# Go backend (gobackend.aar)
+# Go backend (gobackend.aar) - CRITICAL for release builds
 -keep class gobackend.** { *; }
 -keep class go.** { *; }
+-keep interface gobackend.** { *; }
+-keepclassmembers class gobackend.** { *; }
+
+# Go mobile binding internals
+-keep class org.golang.** { *; }
+-dontwarn org.golang.**
 
 # FFmpeg Kit
 -keep class com.arthenica.ffmpegkit.** { *; }
 -keep class com.arthenica.smartexception.** { *; }
+# FFmpeg Kit (new fork package)
+-keep class com.antonkarpenko.ffmpegkit.** { *; }
+-keep class com.antonkarpenko.smartexception.** { *; }
 
 # Apache Tika (if used by FFmpeg)
 -dontwarn org.apache.tika.**
@@ -30,15 +40,77 @@
     native <methods>;
 }
 
-# Kotlin coroutines
+# Kotlin coroutines - expanded rules
 -keepnames class kotlinx.coroutines.internal.MainDispatcherFactory {}
 -keepnames class kotlinx.coroutines.CoroutineExceptionHandler {}
 -keepclassmembers class kotlinx.coroutines.** {
     volatile <fields>;
 }
+-keepclassmembernames class kotlinx.** {
+    volatile <fields>;
+}
+-dontwarn kotlinx.coroutines.**
+
+# Kotlin serialization
+-keepattributes RuntimeVisibleAnnotations,AnnotationDefault
+-dontwarn kotlin.**
+-keep class kotlin.** { *; }
+-keep class kotlin.Metadata { *; }
+
+# Keep MainActivity and related classes
+-keep class com.zarz.spotiflac.** { *; }
 
 # Prevent R8 from removing metadata
 -keepattributes *Annotation*
 -keepattributes SourceFile,LineNumberTable
 -keepattributes Signature
 -keepattributes Exceptions
+-keepattributes InnerClasses
+-keepattributes EnclosingMethod
+
+# JSON parsing (used by Go backend responses)
+-keep class org.json.** { *; }
+
+# Shared Preferences
+-keep class androidx.datastore.** { *; }
+-dontwarn androidx.datastore.**
+
+# Flutter Plugins - CRITICAL: Prevent R8 from removing plugin implementations
+# Path Provider
+-keep class io.flutter.plugins.pathprovider.** { *; }
+-keep class dev.flutter.pigeon.** { *; }
+
+# Local Notifications
+-keep class com.dexterous.** { *; }
+-keep class com.dexterous.flutterlocalnotifications.** { *; }
+
+# Receive Sharing Intent
+-keep class com.kasem.receive_sharing_intent.** { *; }
+
+# Permission Handler
+-keep class com.baseflow.permissionhandler.** { *; }
+
+# File Picker
+-keep class com.mr.flutter.plugin.filepicker.** { *; }
+
+# URL Launcher
+-keep class io.flutter.plugins.urllauncher.** { *; }
+
+# Share Plus
+-keep class dev.fluttercommunity.plus.share.** { *; }
+
+# Device Info Plus
+-keep class dev.fluttercommunity.plus.device_info.** { *; }
+
+# Open File
+-keep class com.crazecoder.openfile.** { *; }
+
+# Sqflite
+-keep class com.tekartik.sqflite.** { *; }
+
+# Dynamic Color
+-keep class io.material.** { *; }
+
+# Keep all Flutter plugin registrants
+-keep class io.flutter.plugins.GeneratedPluginRegistrant { *; }
+-keep class ** extends io.flutter.embedding.engine.plugins.FlutterPlugin { *; }

android/app/src/main/AndroidManifest.xml

@@ -12,6 +12,7 @@
     <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
     <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
     <uses-permission android:name="android.permission.WAKE_LOCK" />
@@ -20,9 +21,10 @@
         android:label="SpotiFLAC"
         android:name="${applicationName}"
         android:icon="@mipmap/ic_launcher"
-        android:requestLegacyExternalStorage="true"
-        android:usesCleartextTraffic="true"
-        android:enableOnBackInvokedCallback="true">
+        android:usesCleartextTraffic="false"
+        android:networkSecurityConfig="@xml/network_security_config"
+        android:enableOnBackInvokedCallback="true"
+        android:localeConfig="@xml/locale_config">
 
         <activity
             android:name=".MainActivity"
@@ -43,7 +45,7 @@
                 <category android:name="android.intent.category.LAUNCHER"/>
             </intent-filter>
 
-            <!-- Handle Spotify URL sharing -->
+            <!-- Handle music URL sharing (Spotify, Deezer, Tidal, YT Music) -->
             <intent-filter>
                 <action android:name="android.intent.action.SEND" />
                 <category android:name="android.intent.category.DEFAULT" />
@@ -57,6 +59,33 @@
                 <category android:name="android.intent.category.BROWSABLE" />
                 <data android:scheme="https" android:host="open.spotify.com" />
             </intent-filter>
+
+            <!-- Handle Deezer deep links -->
+            <intent-filter android:autoVerify="true">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="https" android:host="www.deezer.com" />
+                <data android:scheme="https" android:host="deezer.com" />
+                <data android:scheme="https" android:host="deezer.page.link" />
+            </intent-filter>
+
+            <!-- Handle Tidal deep links -->
+            <intent-filter android:autoVerify="true">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="https" android:host="tidal.com" />
+                <data android:scheme="https" android:host="listen.tidal.com" />
+            </intent-filter>
+
+            <!-- Handle YouTube Music deep links -->
+            <intent-filter android:autoVerify="true">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="https" android:host="music.youtube.com" />
+            </intent-filter>
         </activity>
 
         <!-- Download Service -->

android/app/src/main/kotlin/com/zarz/spotiflac/DownloadService.kt

@@ -104,7 +104,7 @@ class DownloadService : Service() {
                 updateNotification(progress, total)
             }
         }
-        return START_STICKY
+        return START_NOT_STICKY
     }
     
     override fun onBind(intent: Intent?): IBinder? = null
@@ -115,10 +115,8 @@ class DownloadService : Service() {
      * We must call stopSelf() within a few seconds to avoid a crash.
      */
     override fun onTimeout(startId: Int, fgsType: Int) {
-        // Log the timeout for debugging
         android.util.Log.w("DownloadService", "Foreground service timeout reached (6 hours limit). Stopping service.")
         
-        // Gracefully stop the service
         stopForegroundService()
     }
     
@@ -139,14 +137,13 @@ class DownloadService : Service() {
     
     private fun startForegroundService() {
         isRunning = true
-        
-        // Acquire wake lock to prevent CPU sleep
+
         val powerManager = getSystemService(Context.POWER_SERVICE) as PowerManager
         wakeLock = powerManager.newWakeLock(
             PowerManager.PARTIAL_WAKE_LOCK,
             WAKELOCK_TAG
         ).apply {
-            acquire(60 * 60 * 1000L) // 1 hour max
+            acquire(60 * 60 * 1000L)
         }
         
         val notification = buildNotification(0, 0)

android/app/src/main/res/values/colors.xml

@@ -1,4 +1,4 @@
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
-    <color name="ic_launcher_background">#1a1a2e</color>
+    <color name="ic_launcher_background">#000000</color>
 </resources>

android/app/src/main/res/xml/locale_config.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<locale-config xmlns:android="http://schemas.android.com/apk/res/android">
+    <locale android:name="en" />
+    <locale android:name="ru" />
+    <locale android:name="es-ES" />
+    <locale android:name="id" />
+    <locale android:name="pt-PT" />
+    <locale android:name="ja" />
+    <locale android:name="tr" />
+    <locale android:name="de" />
+    <locale android:name="fr" />
+    <locale android:name="hi" />
+    <locale android:name="ko" />
+    <locale android:name="nl" />
+    <locale android:name="zh" />
+</locale-config>

android/app/src/main/res/xml/network_security_config.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false" />
+
+    <!-- Allow local loopback cleartext for FFmpeg live decrypt tunnel only. -->
+    <domain-config cleartextTrafficPermitted="true">
+        <domain includeSubdomains="true">localhost</domain>
+        <domain includeSubdomains="true">127.0.0.1</domain>
+    </domain-config>
+</network-security-config>

android/build.gradle.kts

@@ -22,7 +22,7 @@ subprojects {
             }
             
             // Add desugaring dependency to all Android subprojects
-            project.dependencies.add("coreLibraryDesugaring", "com.android.tools:desugar_jdk_libs:2.1.4")
+            project.dependencies.add("coreLibraryDesugaring", "com.android.tools:desugar_jdk_libs:2.1.5")
         }
         
         tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {

android/gradle.properties

@@ -1,2 +1,2 @@
-org.gradle.jvmargs=-Xmx8G -XX:MaxMetaspaceSize=4G -XX:ReservedCodeCacheSize=512m -XX:+HeapDumpOnOutOfMemoryError
+org.gradle.jvmargs=-Xmx4G -XX:MaxMetaspaceSize=2G -XX:ReservedCodeCacheSize=256m -XX:+HeapDumpOnOutOfMemoryError
 android.useAndroidX=true

android/gradle/wrapper/gradle-wrapper.properties

@@ -2,4 +2,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.4.1-all.zip

android/settings.gradle.kts

@@ -19,8 +19,8 @@ pluginManagement {
 
 plugins {
     id("dev.flutter.flutter-plugin-loader") version "1.0.0"
-    id("com.android.application") version "8.11.1" apply false
-    id("org.jetbrains.kotlin.android") version "2.3.0" apply false
+    id("com.android.application") version "8.13.2" apply false
+    id("org.jetbrains.kotlin.android") version "2.3.20" apply false
 }
 
 include(":app")

apps.json

@@ -0,0 +1,18 @@
+{
+  "name": "SpotiFLAC Source",
+  "identifier": "com.zarzet.spotiflac.source",
+  "subtitle": "FLAC Downloader for iOS",
+  "apps": [
+    {
+      "name": "SpotiFLAC",
+      "bundleIdentifier": "com.zarzet.spotiflac",
+      "developerName": "zarzet",
+      "version": "3.9.0",
+      "versionDate": "2026-03-25",
+      "downloadURL": "https://github.com/zarzet/SpotiFLAC-Mobile/releases/download/v3.9.0/SpotiFLAC-v3.9.0-ios-unsigned.ipa",
+      "localizedDescription": "Mobile version of SpotiFLAC written in Flutter. Download Tracks in true FLAC from Tidal, Qobuz, & Amazon Music.",
+      "iconURL": "https://raw.githubusercontent.com/zarzet/SpotiFLAC-Mobile/main/assets/images/logo.png",
+      "size": 34477323
+    }
+  ]
+}

build_assets/ffmpeg_service_ios.dart

@@ -1,335 +0,0 @@
-import 'dart:io';
-import 'package:ffmpeg_kit_flutter_new_audio/ffmpeg_kit.dart';
-import 'package:ffmpeg_kit_flutter_new_audio/return_code.dart';
-import 'package:spotiflac_android/utils/logger.dart';
-
-final _log = AppLogger('FFmpeg');
-
-/// FFmpeg service for iOS using ffmpeg_kit_flutter plugin
-class FFmpegServiceIOS {
-  /// Execute FFmpeg command and return result
-  static Future<FFmpegResultIOS> _execute(String command) async {
-    try {
-      final session = await FFmpegKit.execute(command);
-      final returnCode = await session.getReturnCode();
-      final output = await session.getOutput() ?? '';
-      return FFmpegResultIOS(
-        success: ReturnCode.isSuccess(returnCode),
-        returnCode: returnCode?.getValue() ?? -1,
-        output: output,
-      );
-    } catch (e) {
-      _log.e('FFmpeg execute error: $e');
-      return FFmpegResultIOS(success: false, returnCode: -1, output: e.toString());
-    }
-  }
-
-  /// Convert M4A (DASH segments) to FLAC
-  static Future<String?> convertM4aToFlac(String inputPath) async {
-    final outputPath = inputPath.replaceAll('.m4a', '.flac');
-    final command = '-i "$inputPath" -c:a flac -compression_level 8 "$outputPath" -y';
-    final result = await _execute(command);
-
-    if (result.success) {
-      try {
-        await File(inputPath).delete();
-      } catch (_) {}
-      return outputPath;
-    }
-
-    _log.e('M4A to FLAC conversion failed: ${result.output}');
-    return null;
-  }
-
-  /// Convert FLAC to MP3
-  /// If deleteOriginal is true, deletes the FLAC file after conversion
-  static Future<String?> convertFlacToMp3(
-    String inputPath, {
-    String bitrate = '320k',
-    bool deleteOriginal = true,
-  }) async {
-    // Convert in same folder, just change extension
-    final outputPath = inputPath.replaceAll('.flac', '.mp3');
-
-    final command = '-i "$inputPath" -codec:a libmp3lame -b:a $bitrate -map 0:a -map_metadata 0 -id3v2_version 3 "$outputPath" -y';
-    final result = await _execute(command);
-
-    if (result.success) {
-      // Delete original FLAC if requested
-      if (deleteOriginal) {
-        try {
-          await File(inputPath).delete();
-        } catch (_) {}
-      }
-      return outputPath;
-    }
-    _log.e('FLAC to MP3 conversion failed: ${result.output}');
-    return null;
-  }
-
-  /// Convert FLAC to M4A
-  static Future<String?> convertFlacToM4a(String inputPath, {String codec = 'aac', String bitrate = '256k'}) async {
-    final dir = File(inputPath).parent.path;
-    final baseName = inputPath.split(Platform.pathSeparator).last.replaceAll('.flac', '');
-    final outputDir = '$dir${Platform.pathSeparator}M4A';
-    await Directory(outputDir).create(recursive: true);
-    final outputPath = '$outputDir${Platform.pathSeparator}$baseName.m4a';
-
-    String command;
-    if (codec == 'alac') {
-      command = '-i "$inputPath" -codec:a alac -map 0:a -map_metadata 0 "$outputPath" -y';
-    } else {
-      command = '-i "$inputPath" -codec:a aac -b:a $bitrate -map 0:a -map_metadata 0 "$outputPath" -y';
-    }
-
-    final result = await _execute(command);
-    if (result.success) return outputPath;
-    _log.e('FLAC to M4A conversion failed: ${result.output}');
-    return null;
-  }
-
-  /// Embed cover art to FLAC file
-  static Future<String?> embedCover(String flacPath, String coverPath) async {
-    final tempOutput = '$flacPath.tmp';
-    final command = '-i "$flacPath" -i "$coverPath" -map 0:a -map 1:0 -c copy -metadata:s:v title="Album cover" -metadata:s:v comment="Cover (front)" -disposition:v attached_pic "$tempOutput" -y';
-
-    final result = await _execute(command);
-
-    if (result.success) {
-      try {
-        await File(flacPath).delete();
-        await File(tempOutput).rename(flacPath);
-        return flacPath;
-      } catch (e) {
-        _log.e('Failed to replace file after cover embed: $e');
-        return null;
-      }
-    }
-
-    try {
-      final tempFile = File(tempOutput);
-      if (await tempFile.exists()) await tempFile.delete();
-    } catch (_) {}
-
-    _log.e('Cover embed failed: ${result.output}');
-    return null;
-  }
-
-  /// Embed metadata and cover art to FLAC file
-  /// Returns the file path on success, null on failure
-  static Future<String?> embedMetadata({
-    required String flacPath,
-    String? coverPath,
-    Map<String, String>? metadata,
-  }) async {
-    final tempOutput = '$flacPath.tmp';
-    
-    // Construct command
-    final StringBuffer cmdBuffer = StringBuffer();
-    cmdBuffer.write('-i "$flacPath" ');
-    
-    // Add cover input if available
-    if (coverPath != null) {
-      cmdBuffer.write('-i "$coverPath" ');
-    }
-    
-    // Map audio stream
-    cmdBuffer.write('-map 0:a ');
-    
-    // Map cover stream if available
-    if (coverPath != null) {
-      cmdBuffer.write('-map 1:0 ');
-      cmdBuffer.write('-c:v copy ');
-      cmdBuffer.write('-disposition:v attached_pic ');
-      cmdBuffer.write('-metadata:s:v title="Album cover" ');
-      cmdBuffer.write('-metadata:s:v comment="Cover (front)" ');
-    }
-    
-    // Copy audio codec (don't re-encode)
-    cmdBuffer.write('-c:a copy ');
-    
-    // Add text metadata
-    if (metadata != null) {
-      metadata.forEach((key, value) {
-        // Sanitize value: escape double quotes
-        final sanitizedValue = value.replaceAll('"', '\\"');
-        cmdBuffer.write('-metadata $key="$sanitizedValue" ');
-      });
-    }
-    
-    cmdBuffer.write('"$tempOutput" -y');
-    
-    final command = cmdBuffer.toString();
-    _log.d('Executing FFmpeg command: $command');
-
-    final result = await _execute(command);
-
-    if (result.success) {
-      try {
-        await File(flacPath).delete();
-        await File(tempOutput).rename(flacPath);
-        return flacPath;
-      } catch (e) {
-        _log.e('Failed to replace file after metadata embed: $e');
-        return null;
-      }
-    }
-
-    // Clean up temp file if exists
-    try {
-      final tempFile = File(tempOutput);
-      if (await tempFile.exists()) {
-        await tempFile.delete();
-      }
-    } catch (_) {}
-
-    _log.e('Metadata/Cover embed failed: ${result.output}');
-    return null;
-  }
-
-  /// Embed metadata and cover art to MP3 file using ID3v2 tags
-  /// Returns the file path on success, null on failure
-  static Future<String?> embedMetadataToMp3({
-    required String mp3Path,
-    String? coverPath,
-    Map<String, String>? metadata,
-  }) async {
-    final tempOutput = '$mp3Path.tmp';
-    
-    final StringBuffer cmdBuffer = StringBuffer();
-    cmdBuffer.write('-i "$mp3Path" ');
-    
-    if (coverPath != null) {
-      cmdBuffer.write('-i "$coverPath" ');
-    }
-    
-    cmdBuffer.write('-map 0:a ');
-    
-    if (coverPath != null) {
-      cmdBuffer.write('-map 1:0 ');
-      cmdBuffer.write('-c:v:0 copy ');
-      cmdBuffer.write('-id3v2_version 3 ');
-      cmdBuffer.write('-metadata:s:v title="Album cover" ');
-      cmdBuffer.write('-metadata:s:v comment="Cover (front)" ');
-    }
-    
-    cmdBuffer.write('-c:a copy ');
-    
-    if (metadata != null) {
-      // Convert FLAC/Vorbis tags to ID3v2 tags for MP3
-      final id3Metadata = _convertToId3Tags(metadata);
-      id3Metadata.forEach((key, value) {
-        final sanitizedValue = value.replaceAll('"', '\\"');
-        cmdBuffer.write('-metadata $key="$sanitizedValue" ');
-      });
-    }
-    
-    cmdBuffer.write('-id3v2_version 3 "$tempOutput" -y');
-    
-    final command = cmdBuffer.toString();
-    _log.d('Executing FFmpeg MP3 embed command: $command');
-
-    final result = await _execute(command);
-
-    if (result.success) {
-      try {
-        await File(mp3Path).delete();
-        await File(tempOutput).rename(mp3Path);
-        _log.d('MP3 metadata embedded successfully');
-        return mp3Path;
-      } catch (e) {
-        _log.e('Failed to replace MP3 file after metadata embed: $e');
-        return null;
-      }
-    }
-
-    try {
-      final tempFile = File(tempOutput);
-      if (await tempFile.exists()) {
-        await tempFile.delete();
-      }
-    } catch (_) {}
-
-    _log.e('MP3 Metadata/Cover embed failed: ${result.output}');
-    return null;
-  }
-
-  /// Convert FLAC/Vorbis comment tags to ID3v2 compatible tags
-  static Map<String, String> _convertToId3Tags(Map<String, String> vorbisMetadata) {
-    final id3Map = <String, String>{};
-    
-    for (final entry in vorbisMetadata.entries) {
-      final key = entry.key.toUpperCase();
-      final value = entry.value;
-      
-      // Map Vorbis comments to ID3v2 frame names
-      switch (key) {
-        case 'TITLE':
-          id3Map['title'] = value;
-          break;
-        case 'ARTIST':
-          id3Map['artist'] = value;
-          break;
-        case 'ALBUM':
-          id3Map['album'] = value;
-          break;
-        case 'ALBUMARTIST':
-          id3Map['album_artist'] = value;
-          break;
-        case 'TRACKNUMBER':
-        case 'TRACK':
-          id3Map['track'] = value;
-          break;
-        case 'DISCNUMBER':
-        case 'DISC':
-          id3Map['disc'] = value;
-          break;
-        case 'DATE':
-        case 'YEAR':
-          id3Map['date'] = value;
-          break;
-        case 'ISRC':
-          id3Map['TSRC'] = value; // ID3v2 ISRC frame
-          break;
-        case 'LYRICS':
-        case 'UNSYNCEDLYRICS':
-          id3Map['lyrics'] = value;
-          break;
-        default:
-          // Pass through other tags as-is
-          id3Map[key.toLowerCase()] = value;
-      }
-    }
-    
-    return id3Map;
-  }
-
-  /// Check if FFmpeg is available
-  static Future<bool> isAvailable() async {
-    try {
-      final session = await FFmpegKit.execute('-version');
-      final returnCode = await session.getReturnCode();
-      return ReturnCode.isSuccess(returnCode);
-    } catch (e) {
-      return false;
-    }
-  }
-
-  /// Get FFmpeg version info
-  static Future<String?> getVersion() async {
-    try {
-      final session = await FFmpegKit.execute('-version');
-      return await session.getOutput();
-    } catch (e) {
-      return null;
-    }
-  }
-}
-
-class FFmpegResultIOS {
-  final bool success;
-  final int returnCode;
-  final String output;
-
-  FFmpegResultIOS({required this.success, required this.returnCode, required this.output});
-}

cliff.toml

@@ -0,0 +1,103 @@
+# git-cliff configuration for SpotiFLAC Mobile
+# https://git-cliff.org/docs/configuration
+
+[changelog]
+# Template for the changelog body
+body = """
+{%- macro remote_url() -%}
+  https://github.com/zarzet/SpotiFLAC-Mobile
+{%- endmacro -%}
+
+{% if version %}\
+    ## {{ version | trim_start_matches(pat="v") }}
+{% else %}\
+    ## Unreleased
+{% endif %}\
+
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | striptags | trim | upper_first }}
+    {% for commit in commits %}
+        - {% if commit.scope %}**{{ commit.scope }}**: {% endif %}\
+            {{ commit.message | upper_first }}\
+            {% if commit.github.pr_number %} \
+                ([#{{ commit.github.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.github.pr_number }}))\
+            {% endif %}\
+            {%- if commit.github.username and commit.github.username != "zarzet" %} by [@{{ commit.github.username }}](https://github.com/{{ commit.github.username }}){%- endif %}
+    {%- endfor %}
+{% endfor %}
+
+{%- if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
+
+  ### New Contributors
+{%- for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
+  * @{{ contributor.username }} made their first contribution
+    {%- if contributor.pr_number %} in \
+      [#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \
+    {%- endif %}
+{%- endfor %}
+{%- endif -%}
+
+{% if version %}
+    {% if previous.version %}
+      **Full Changelog**: [{{ previous.version }}...{{ version }}]({{ self::remote_url() }}/compare/{{ previous.version }}...{{ version }})
+    {% endif %}
+{% else -%}
+    {% raw %}\n{% endraw %}
+{% endif %}
+"""
+# Remove leading and trailing whitespace
+trim = true
+
+[git]
+# Parse conventional commits
+conventional_commits = true
+filter_unconventional = true
+
+# Process each line of a commit as an individual commit
+split_commits = false
+
+# Regex for preprocessing the commit messages
+commit_preprocessors = [
+  # Strip conventional commit prefix for cleaner messages
+  # (group header already shows the type)
+]
+
+# Regex for parsing and grouping commits
+commit_parsers = [
+  # Skip noise: translation commits from Crowdin
+  { message = "^New translations", skip = true },
+  { message = "^Update source file", skip = true },
+  # Skip merge commits
+  { message = "^Merge", skip = true },
+  # Skip version bump commits
+  { message = "^v\\d+", skip = true },
+  { message = "^chore: update VirusTotal", skip = true },
+
+  # Group by conventional commit type
+  { message = "^feat", group = "<!-- 0 -->New Features" },
+  { message = "^fix", group = "<!-- 1 -->Bug Fixes" },
+  { message = "^perf", group = "<!-- 2 -->Performance" },
+  { message = "^refactor", group = "<!-- 3 -->Refactoring" },
+  { message = "^doc", group = "<!-- 4 -->Documentation" },
+  { message = "^style", group = "<!-- 5 -->Styling" },
+  { message = "^test", group = "<!-- 6 -->Testing" },
+  { message = "^chore\\(deps\\)", group = "<!-- 7 -->Dependencies" },
+  { message = "^chore\\(l10n\\)", skip = true },
+  { message = "^chore|^ci", group = "<!-- 8 -->Chores" },
+]
+
+# Protect breaking changes from being skipped
+protect_breaking_commits = true
+
+# Filter out commits by matching patterns
+filter_commits = false
+
+# Tag pattern for version detection
+tag_pattern = "v[0-9].*"
+
+# Sort commits by newest first
+sort_commits = "newest"
+
+[remote.github]
+owner = "zarzet"
+repo = "SpotiFLAC-Mobile"

go_backend/amazon.go

@@ -1,639 +0,0 @@
-package gobackend
-
-import (
-	"bufio"
-	"context"
-	"encoding/base64"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"net/http"
-	"net/url"
-	"os"
-	"path/filepath"
-	"strings"
-	"sync"
-	"time"
-)
-
-type AmazonDownloader struct {
-	client           *http.Client
-	regions          []string
-	lastAPICallTime  time.Time
-	apiCallCount     int
-	apiCallResetTime time.Time
-}
-
-var (
-	globalAmazonDownloader *AmazonDownloader
-	amazonDownloaderOnce   sync.Once
-	amazonRateLimitMu      sync.Mutex
-)
-
-// DoubleDoubleSubmitResponse is the response from DoubleDouble submit endpoint
-type DoubleDoubleSubmitResponse struct {
-	Success bool   `json:"success"`
-	ID      string `json:"id"`
-}
-
-type DoubleDoubleStatusResponse struct {
-	Status         string `json:"status"`
-	FriendlyStatus string `json:"friendlyStatus"`
-	URL            string `json:"url"`
-	Current        struct {
-		Name   string `json:"name"`
-		Artist string `json:"artist"`
-	} `json:"current"`
-}
-
-func amazonArtistsMatch(expectedArtist, foundArtist string) bool {
-	normExpected := strings.ToLower(strings.TrimSpace(expectedArtist))
-	normFound := strings.ToLower(strings.TrimSpace(foundArtist))
-
-	if normExpected == normFound {
-		return true
-	}
-
-	if strings.Contains(normExpected, normFound) || strings.Contains(normFound, normExpected) {
-		return true
-	}
-
-	expectedFirst := strings.Split(normExpected, ",")[0]
-	expectedFirst = strings.Split(expectedFirst, " feat")[0]
-	expectedFirst = strings.Split(expectedFirst, " ft.")[0]
-	expectedFirst = strings.TrimSpace(expectedFirst)
-
-	foundFirst := strings.Split(normFound, ",")[0]
-	foundFirst = strings.Split(foundFirst, " feat")[0]
-	foundFirst = strings.Split(foundFirst, " ft.")[0]
-	foundFirst = strings.TrimSpace(foundFirst)
-
-	if expectedFirst == foundFirst {
-		return true
-	}
-
-	if strings.Contains(expectedFirst, foundFirst) || strings.Contains(foundFirst, expectedFirst) {
-		return true
-	}
-
-	expectedASCII := amazonIsASCIIString(expectedArtist)
-	foundASCII := amazonIsASCIIString(foundArtist)
-	if expectedASCII != foundASCII {
-		GoLog("[Amazon] Artist names in different scripts, assuming match: '%s' vs '%s'\n", expectedArtist, foundArtist)
-		return true
-	}
-
-	return false
-}
-
-func amazonIsASCIIString(s string) bool {
-	for _, r := range s {
-		if r > 127 {
-			return false
-		}
-	}
-	return true
-}
-
-func NewAmazonDownloader() *AmazonDownloader {
-	amazonDownloaderOnce.Do(func() {
-		globalAmazonDownloader = &AmazonDownloader{
-			client:           NewHTTPClientWithTimeout(120 * time.Second), // 120s timeout like PC
-			regions:          []string{"us", "eu"},                        // Same regions as PC
-			apiCallResetTime: time.Now(),
-		}
-	})
-	return globalAmazonDownloader
-}
-
-// waitForRateLimit implements rate limiting similar to PC version
-func (a *AmazonDownloader) waitForRateLimit() {
-	amazonRateLimitMu.Lock()
-	defer amazonRateLimitMu.Unlock()
-
-	now := time.Now()
-
-	if now.Sub(a.apiCallResetTime) >= time.Minute {
-		a.apiCallCount = 0
-		a.apiCallResetTime = now
-	}
-
-	if a.apiCallCount >= 9 {
-		waitTime := time.Minute - now.Sub(a.apiCallResetTime)
-		if waitTime > 0 {
-			GoLog("[Amazon] Rate limit reached, waiting %v...\n", waitTime.Round(time.Second))
-			time.Sleep(waitTime)
-			a.apiCallCount = 0
-			a.apiCallResetTime = time.Now()
-		}
-	}
-
-	if !a.lastAPICallTime.IsZero() {
-		timeSinceLastCall := now.Sub(a.lastAPICallTime)
-		minDelay := 7 * time.Second
-		if timeSinceLastCall < minDelay {
-			waitTime := minDelay - timeSinceLastCall
-			GoLog("[Amazon] Rate limiting: waiting %v...\n", waitTime.Round(time.Second))
-			time.Sleep(waitTime)
-		}
-	}
-
-	a.lastAPICallTime = time.Now()
-	a.apiCallCount++
-}
-
-// Uses same service as PC version (doubledouble.top)
-func (a *AmazonDownloader) GetAvailableAPIs() []string {
-	// DoubleDouble service regions (same as PC)
-	// Format: https://{region}.doubledouble.top
-	var apis []string
-	for _, region := range a.regions {
-		apis = append(apis, fmt.Sprintf("https://%s.doubledouble.top", region))
-	}
-	return apis
-}
-
-// downloadFromDoubleDoubleService downloads a track using DoubleDouble service (same as PC)
-// This uses submit → poll → download mechanism
-// Internal function - not exported to gomobile
-func (a *AmazonDownloader) downloadFromDoubleDoubleService(amazonURL, _ string) (string, string, string, error) {
-	var lastError error
-
-	for _, region := range a.regions {
-		GoLog("[Amazon] Trying region: %s...\n", region)
-
-		serviceBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly8=")               // https://
-		serviceDomain, _ := base64.StdEncoding.DecodeString("LmRvdWJsZWRvdWJsZS50b3A=") // .doubledouble.top
-		baseURL := fmt.Sprintf("%s%s%s", string(serviceBase), region, string(serviceDomain))
-
-		encodedURL := url.QueryEscape(amazonURL)
-		submitURL := fmt.Sprintf("%s/dl?url=%s", baseURL, encodedURL)
-
-		a.waitForRateLimit()
-
-		req, err := http.NewRequest("GET", submitURL, nil)
-		if err != nil {
-			lastError = fmt.Errorf("failed to create request: %w", err)
-			continue
-		}
-
-		req.Header.Set("User-Agent", getRandomUserAgent())
-
-		fmt.Println("[Amazon] Submitting download request...")
-
-		// Retry logic for 429 errors (like PC version: 3 retries with 15s wait)
-		var resp *http.Response
-		maxRetries := 3
-		for retry := 0; retry < maxRetries; retry++ {
-			resp, err = a.client.Do(req)
-			if err != nil {
-				lastError = fmt.Errorf("failed to submit request: %w", err)
-				break
-			}
-
-			if resp.StatusCode == 429 { // Too Many Requests
-				resp.Body.Close()
-				if retry < maxRetries-1 {
-					waitTime := 15 * time.Second
-					GoLog("[Amazon] Rate limited (429), waiting %v before retry %d/%d...\n", waitTime, retry+2, maxRetries)
-					time.Sleep(waitTime)
-					continue
-				}
-				lastError = fmt.Errorf("API rate limit exceeded after %d retries", maxRetries)
-				break
-			}
-
-			if resp.StatusCode != 200 {
-				resp.Body.Close()
-				lastError = fmt.Errorf("submit failed with status %d", resp.StatusCode)
-				break
-			}
-
-			// Success - break retry loop
-			break
-		}
-
-		if err != nil || lastError != nil {
-			if resp != nil {
-				resp.Body.Close()
-			}
-			continue
-		}
-
-		var submitResp DoubleDoubleSubmitResponse
-		if err := json.NewDecoder(resp.Body).Decode(&submitResp); err != nil {
-			resp.Body.Close()
-			lastError = fmt.Errorf("failed to decode submit response: %w", err)
-			continue
-		}
-		resp.Body.Close()
-
-		if !submitResp.Success || submitResp.ID == "" {
-			lastError = fmt.Errorf("submit request failed")
-			continue
-		}
-
-		downloadID := submitResp.ID
-		GoLog("[Amazon] Download ID: %s\n", downloadID)
-
-		// Step 2: Poll for completion
-		statusURL := fmt.Sprintf("%s/dl/%s", baseURL, downloadID)
-		fmt.Println("[Amazon] Waiting for download to complete...")
-
-		maxWait := 300 * time.Second // 5 minutes max wait
-		elapsed := time.Duration(0)
-		pollInterval := 3 * time.Second
-
-		for elapsed < maxWait {
-			time.Sleep(pollInterval)
-			elapsed += pollInterval
-
-			statusReq, err := http.NewRequest("GET", statusURL, nil)
-			if err != nil {
-				continue
-			}
-
-			statusReq.Header.Set("User-Agent", getRandomUserAgent())
-
-			statusResp, err := a.client.Do(statusReq)
-			if err != nil {
-				fmt.Printf("\r[Amazon] Status check failed, retrying...")
-				continue
-			}
-
-			if statusResp.StatusCode != 200 {
-				statusResp.Body.Close()
-				fmt.Printf("\r[Amazon] Status check failed (status %d), retrying...", statusResp.StatusCode)
-				continue
-			}
-
-			var status DoubleDoubleStatusResponse
-			if err := json.NewDecoder(statusResp.Body).Decode(&status); err != nil {
-				statusResp.Body.Close()
-				fmt.Printf("\r[Amazon] Invalid JSON response, retrying...")
-				continue
-			}
-			statusResp.Body.Close()
-
-			if status.Status == "done" {
-				fmt.Println("\n[Amazon] Download ready!")
-
-				fileURL := status.URL
-				if strings.HasPrefix(fileURL, "./") {
-					fileURL = fmt.Sprintf("%s/%s", baseURL, fileURL[2:])
-				} else if strings.HasPrefix(fileURL, "/") {
-					fileURL = fmt.Sprintf("%s%s", baseURL, fileURL)
-				}
-
-				trackName := status.Current.Name
-				artist := status.Current.Artist
-
-				GoLog("[Amazon] Downloading: %s - %s\n", artist, trackName)
-				return fileURL, trackName, artist, nil
-
-			} else if status.Status == "error" {
-				errorMsg := status.FriendlyStatus
-				if errorMsg == "" {
-					errorMsg = "Unknown error"
-				}
-				lastError = fmt.Errorf("processing failed: %s", errorMsg)
-				break
-			} else {
-				// Still processing
-				friendlyStatus := status.FriendlyStatus
-				if friendlyStatus == "" {
-					friendlyStatus = status.Status
-				}
-				fmt.Printf("\r[Amazon] %s...", friendlyStatus)
-			}
-		}
-
-		if elapsed >= maxWait {
-			lastError = fmt.Errorf("download timeout")
-			fmt.Printf("\n[Amazon] Error with %s region: %v\n", region, lastError)
-			continue
-		}
-
-		if lastError != nil {
-			fmt.Printf("\n[Amazon] Error with %s region: %v\n", region, lastError)
-		}
-	}
-
-	return "", "", "", fmt.Errorf("all regions failed. Last error: %v", lastError)
-}
-
-func (a *AmazonDownloader) DownloadFile(downloadURL, outputPath, itemID string) error {
-	ctx := context.Background()
-
-	// Initialize item progress (required for all downloads)
-	if itemID != "" {
-		StartItemProgress(itemID)
-		defer CompleteItemProgress(itemID)
-		ctx = initDownloadCancel(itemID)
-		defer clearDownloadCancel(itemID)
-	}
-
-	if isDownloadCancelled(itemID) {
-		return ErrDownloadCancelled
-	}
-
-	req, err := http.NewRequestWithContext(ctx, "GET", downloadURL, nil)
-	if err != nil {
-		return fmt.Errorf("failed to create request: %w", err)
-	}
-
-	req.Header.Set("User-Agent", getRandomUserAgent())
-
-	resp, err := a.client.Do(req)
-	if err != nil {
-		if isDownloadCancelled(itemID) {
-			return ErrDownloadCancelled
-		}
-		return err
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return fmt.Errorf("download failed: HTTP %d", resp.StatusCode)
-	}
-
-	expectedSize := resp.ContentLength
-	if expectedSize > 0 && itemID != "" {
-		SetItemBytesTotal(itemID, expectedSize)
-	}
-
-	out, err := os.Create(outputPath)
-	if err != nil {
-		return err
-	}
-
-	bufWriter := bufio.NewWriterSize(out, 256*1024)
-
-	var written int64
-	if itemID != "" {
-		pw := NewItemProgressWriter(bufWriter, itemID)
-		written, err = io.Copy(pw, resp.Body)
-	} else {
-		written, err = io.Copy(bufWriter, resp.Body)
-	}
-
-	// Flush buffer before checking for errors
-	flushErr := bufWriter.Flush()
-	closeErr := out.Close()
-
-	if err != nil {
-		os.Remove(outputPath)
-		if isDownloadCancelled(itemID) {
-			return ErrDownloadCancelled
-		}
-		return fmt.Errorf("download interrupted: %w", err)
-	}
-	if flushErr != nil {
-		os.Remove(outputPath)
-		return fmt.Errorf("failed to flush buffer: %w", flushErr)
-	}
-	if closeErr != nil {
-		os.Remove(outputPath)
-		return fmt.Errorf("failed to close file: %w", closeErr)
-	}
-
-	// Verify file size if Content-Length was provided
-	if expectedSize > 0 && written != expectedSize {
-		os.Remove(outputPath)
-		return fmt.Errorf("incomplete download: expected %d bytes, got %d bytes", expectedSize, written)
-	}
-
-	fmt.Printf("\r[Amazon] Downloaded: %.2f MB (Complete)\n", float64(written)/(1024*1024))
-	return nil
-}
-
-// AmazonDownloadResult contains download result with quality info
-type AmazonDownloadResult struct {
-	FilePath    string
-	BitDepth    int
-	SampleRate  int
-	Title       string
-	Artist      string
-	Album       string
-	ReleaseDate string
-	TrackNumber int
-	DiscNumber  int
-	ISRC        string
-}
-
-// Uses DoubleDouble service (same as PC version)
-func downloadFromAmazon(req DownloadRequest) (AmazonDownloadResult, error) {
-	downloader := NewAmazonDownloader()
-
-	if existingFile, exists := checkISRCExistsInternal(req.OutputDir, req.ISRC); exists {
-		return AmazonDownloadResult{FilePath: "EXISTS:" + existingFile}, nil
-	}
-
-	songlink := NewSongLinkClient()
-	var availability *TrackAvailability
-	var err error
-
-	if strings.HasPrefix(req.SpotifyID, "deezer:") {
-		deezerID := strings.TrimPrefix(req.SpotifyID, "deezer:")
-		GoLog("[Amazon] Using Deezer ID for SongLink lookup: %s\n", deezerID)
-		availability, err = songlink.CheckAvailabilityFromDeezer(deezerID)
-	} else if req.SpotifyID != "" {
-		availability, err = songlink.CheckTrackAvailability(req.SpotifyID, req.ISRC)
-	} else {
-		return AmazonDownloadResult{}, fmt.Errorf("no valid Spotify or Deezer ID provided for Amazon lookup")
-	}
-
-	if err != nil {
-		return AmazonDownloadResult{}, fmt.Errorf("failed to check Amazon availability via SongLink: %w", err)
-	}
-
-	if !availability.Amazon || availability.AmazonURL == "" {
-		return AmazonDownloadResult{}, fmt.Errorf("track not available on Amazon Music (SongLink returned no Amazon URL)")
-	}
-
-	if req.OutputDir != "." {
-		if err := os.MkdirAll(req.OutputDir, 0755); err != nil {
-			return AmazonDownloadResult{}, fmt.Errorf("failed to create output directory: %w", err)
-		}
-	}
-
-	// Download using DoubleDouble service (same as PC)
-	downloadURL, trackName, artistName, err := downloader.downloadFromDoubleDoubleService(availability.AmazonURL, req.OutputDir)
-	if err != nil {
-		return AmazonDownloadResult{}, fmt.Errorf("failed to get download URL: %w", err)
-	}
-
-	// Verify artist matches
-	if artistName != "" && !amazonArtistsMatch(req.ArtistName, artistName) {
-		GoLog("[Amazon] Artist mismatch: expected '%s', got '%s'. Rejecting.\n", req.ArtistName, artistName)
-		return AmazonDownloadResult{}, fmt.Errorf("artist mismatch: expected '%s', got '%s'", req.ArtistName, artistName)
-	}
-
-	GoLog("[Amazon] Match found: '%s' by '%s'\n", trackName, artistName)
-
-	filename := buildFilenameFromTemplate(req.FilenameFormat, map[string]interface{}{
-		"title":  req.TrackName,
-		"artist": req.ArtistName,
-		"album":  req.AlbumName,
-		"track":  req.TrackNumber,
-		"year":   extractYear(req.ReleaseDate),
-		"disc":   req.DiscNumber,
-	})
-	filename = sanitizeFilename(filename) + ".flac"
-	outputPath := filepath.Join(req.OutputDir, filename)
-
-	if fileInfo, statErr := os.Stat(outputPath); statErr == nil && fileInfo.Size() > 0 {
-		return AmazonDownloadResult{FilePath: "EXISTS:" + outputPath}, nil
-	}
-
-	// START PARALLEL: Fetch cover and lyrics while downloading audio
-	var parallelResult *ParallelDownloadResult
-	parallelDone := make(chan struct{})
-	go func() {
-		defer close(parallelDone)
-		parallelResult = FetchCoverAndLyricsParallel(
-			req.CoverURL,
-			req.EmbedMaxQualityCover,
-			req.SpotifyID,
-			req.TrackName,
-			req.ArtistName,
-			req.EmbedLyrics,
-			int64(req.DurationMS),
-		)
-	}()
-
-	// Download audio file with item ID for progress tracking
-	if err := downloader.DownloadFile(downloadURL, outputPath, req.ItemID); err != nil {
-		if errors.Is(err, ErrDownloadCancelled) {
-			return AmazonDownloadResult{}, ErrDownloadCancelled
-		}
-		return AmazonDownloadResult{}, fmt.Errorf("download failed: %w", err)
-	}
-
-	// Wait for parallel operations to complete
-	<-parallelDone
-
-	if req.ItemID != "" {
-		SetItemProgress(req.ItemID, 1.0, 0, 0)
-		SetItemFinalizing(req.ItemID)
-	}
-
-	// Log track info from DoubleDouble (for debugging)
-	if trackName != "" && artistName != "" {
-		GoLog("[Amazon] DoubleDouble returned: %s - %s\n", artistName, trackName)
-	}
-
-	existingMeta, metaErr := ReadMetadata(outputPath)
-	actualTrackNum := req.TrackNumber
-	actualDiscNum := req.DiscNumber
-
-	if metaErr == nil && existingMeta != nil {
-		if existingMeta.TrackNumber > 0 && (req.TrackNumber == 0 || req.TrackNumber == 1) {
-			actualTrackNum = existingMeta.TrackNumber
-			GoLog("[Amazon] Using track number from file: %d (request had: %d)\n", actualTrackNum, req.TrackNumber)
-		}
-		if existingMeta.DiscNumber > 0 && (req.DiscNumber == 0 || req.DiscNumber == 1) {
-			actualDiscNum = existingMeta.DiscNumber
-			GoLog("[Amazon] Using disc number from file: %d (request had: %d)\n", actualDiscNum, req.DiscNumber)
-		}
-	}
-
-	// Embed metadata using Spotify data (more accurate than DoubleDouble)
-	// But preserve track/disc numbers from file if they were better
-	metadata := Metadata{
-		Title:       req.TrackName,
-		Artist:      req.ArtistName,
-		Album:       req.AlbumName,
-		AlbumArtist: req.AlbumArtist,
-		Date:        req.ReleaseDate,
-		TrackNumber: actualTrackNum,
-		TotalTracks: req.TotalTracks,
-		DiscNumber:  actualDiscNum,
-		ISRC:        req.ISRC,
-		Genre:       req.Genre,     // From Deezer album metadata
-		Label:       req.Label,     // From Deezer album metadata
-		Copyright:   req.Copyright, // From Deezer album metadata
-	}
-
-	// Use cover data from parallel fetch
-	var coverData []byte
-	if parallelResult != nil && parallelResult.CoverData != nil {
-		coverData = parallelResult.CoverData
-		GoLog("[Amazon] Using parallel-fetched cover (%d bytes)\n", len(coverData))
-	}
-
-	if err := EmbedMetadataWithCoverData(outputPath, metadata, coverData); err != nil {
-		fmt.Printf("Warning: failed to embed metadata: %v\n", err)
-	}
-
-	if req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
-		lyricsMode := req.LyricsMode
-		if lyricsMode == "" {
-			lyricsMode = "embed" // default
-		}
-
-		if lyricsMode == "external" || lyricsMode == "both" {
-			GoLog("[Amazon] Saving external LRC file...\n")
-			if lrcPath, lrcErr := SaveLRCFile(outputPath, parallelResult.LyricsLRC); lrcErr != nil {
-				GoLog("[Amazon] Warning: failed to save LRC file: %v\n", lrcErr)
-			} else {
-				GoLog("[Amazon] LRC file saved: %s\n", lrcPath)
-			}
-		}
-
-		if lyricsMode == "embed" || lyricsMode == "both" {
-			GoLog("[Amazon] Embedding parallel-fetched lyrics (%d lines)...\n", len(parallelResult.LyricsData.Lines))
-			if embedErr := EmbedLyrics(outputPath, parallelResult.LyricsLRC); embedErr != nil {
-				GoLog("[Amazon] Warning: failed to embed lyrics: %v\n", embedErr)
-			} else {
-				fmt.Println("[Amazon] Lyrics embedded successfully")
-			}
-		}
-	} else if req.EmbedLyrics {
-		fmt.Println("[Amazon] No lyrics available from parallel fetch")
-	}
-
-	fmt.Println("[Amazon] ✓ Downloaded successfully from Amazon Music")
-
-	quality, err := GetAudioQuality(outputPath)
-	if err != nil {
-		GoLog("[Amazon] Warning: couldn't read quality from file: %v\n", err)
-	} else {
-		GoLog("[Amazon] Actual quality: %d-bit/%dHz\n", quality.BitDepth, quality.SampleRate)
-	}
-
-	finalMeta, metaReadErr := ReadMetadata(outputPath)
-	if metaReadErr == nil && finalMeta != nil {
-		GoLog("[Amazon] Final metadata from file - Track: %d, Disc: %d, Date: %s\n",
-			finalMeta.TrackNumber, finalMeta.DiscNumber, finalMeta.Date)
-		actualTrackNum = finalMeta.TrackNumber
-		actualDiscNum = finalMeta.DiscNumber
-		if finalMeta.Date != "" {
-			req.ReleaseDate = finalMeta.Date
-		}
-	}
-
-	// Add to ISRC index for fast duplicate checking
-	AddToISRCIndex(req.OutputDir, req.ISRC, outputPath)
-
-	bitDepth := 0
-	sampleRate := 0
-	if err == nil {
-		bitDepth = quality.BitDepth
-		sampleRate = quality.SampleRate
-	}
-
-	return AmazonDownloadResult{
-		FilePath:    outputPath,
-		BitDepth:    bitDepth,
-		SampleRate:  sampleRate,
-		Title:       req.TrackName,
-		Artist:      req.ArtistName,
-		Album:       req.AlbumName,
-		ReleaseDate: req.ReleaseDate,
-		TrackNumber: actualTrackNum,
-		DiscNumber:  actualDiscNum,
-		ISRC:        req.ISRC,
-	}, nil
-}

go_backend/ape_tags.go

@@ -0,0 +1,611 @@
+package gobackend
+
+import (
+	"encoding/binary"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+)
+
+// APEv2 tag format constants.
+const (
+	apeTagPreamble     = "APETAGEX"
+	apeTagHeaderSize   = 32
+	apeTagVersion2     = 2000
+	apeTagFlagHeader   = 1 << 29 // bit 29: this is the header, not the footer
+	apeTagFlagReadOnly = 1 << 0
+	// Item flags: bits 1-2 encode content type
+	apeItemFlagUTF8   = 0 << 1 // 00: UTF-8 text
+	apeItemFlagBinary = 1 << 1 // 01: binary data
+	apeItemFlagLink   = 2 << 1 // 10: external link
+)
+
+// APETagItem represents a single key-value item in an APEv2 tag.
+type APETagItem struct {
+	Key   string
+	Value string
+	Flags uint32
+}
+
+// APETag represents a complete APEv2 tag block.
+type APETag struct {
+	Version  uint32
+	Items    []APETagItem
+	ReadOnly bool
+}
+
+// ReadAPETags reads APEv2 tags from a file.
+// APEv2 tags are typically appended at the end of the file.
+// The layout is: [audio data] [APEv2 header (optional)] [items...] [APEv2 footer]
+// We locate the footer first (last 32 bytes), then read the tag block.
+func ReadAPETags(filePath string) (*APETag, error) {
+	f, err := os.Open(filePath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open file: %w", err)
+	}
+	defer f.Close()
+
+	fi, err := f.Stat()
+	if err != nil {
+		return nil, fmt.Errorf("failed to stat file: %w", err)
+	}
+	fileSize := fi.Size()
+
+	if fileSize < apeTagHeaderSize {
+		return nil, fmt.Errorf("file too small for APE tag")
+	}
+
+	// Try to find APE tag footer at the end of file.
+	// The footer is the last 32 bytes before any ID3v1 tag (128 bytes).
+	tag, err := readAPETagAtOffset(f, fileSize, fileSize-apeTagHeaderSize)
+	if err == nil {
+		return tag, nil
+	}
+
+	// Retry: skip ID3v1 tag (128 bytes) if present
+	if fileSize > apeTagHeaderSize+128 {
+		tag, err = readAPETagAtOffset(f, fileSize, fileSize-apeTagHeaderSize-128)
+		if err == nil {
+			return tag, nil
+		}
+	}
+
+	return nil, fmt.Errorf("no APEv2 tag found")
+}
+
+func readAPETagAtOffset(f *os.File, fileSize, footerOffset int64) (*APETag, error) {
+	if footerOffset < 0 || footerOffset+apeTagHeaderSize > fileSize {
+		return nil, fmt.Errorf("invalid footer offset")
+	}
+
+	footer := make([]byte, apeTagHeaderSize)
+	if _, err := f.ReadAt(footer, footerOffset); err != nil {
+		return nil, fmt.Errorf("failed to read APE footer: %w", err)
+	}
+
+	if string(footer[0:8]) != apeTagPreamble {
+		return nil, fmt.Errorf("APE preamble not found")
+	}
+
+	version := binary.LittleEndian.Uint32(footer[8:12])
+	tagSize := binary.LittleEndian.Uint32(footer[12:16]) // size of items + footer (32 bytes)
+	itemCount := binary.LittleEndian.Uint32(footer[16:20])
+	flags := binary.LittleEndian.Uint32(footer[20:24])
+
+	if version != apeTagVersion2 && version != 1000 {
+		return nil, fmt.Errorf("unsupported APE tag version: %d", version)
+	}
+	if tagSize < apeTagHeaderSize {
+		return nil, fmt.Errorf("APE tag size too small: %d", tagSize)
+	}
+	if itemCount > 1000 {
+		return nil, fmt.Errorf("APE tag item count too large: %d", itemCount)
+	}
+
+	// This should be the footer (bit 29 clear)
+	isHeader := (flags & apeTagFlagHeader) != 0
+	if isHeader {
+		return nil, fmt.Errorf("expected APE footer but found header")
+	}
+
+	// tagSize includes items + footer (32 bytes), but NOT the header.
+	itemsSize := int64(tagSize) - apeTagHeaderSize
+	if itemsSize < 0 {
+		return nil, fmt.Errorf("invalid APE tag: items size negative")
+	}
+
+	itemsOffset := footerOffset - itemsSize
+	if itemsOffset < 0 {
+		return nil, fmt.Errorf("APE tag items extend before file start")
+	}
+
+	itemsData := make([]byte, itemsSize)
+	if _, err := f.ReadAt(itemsData, itemsOffset); err != nil {
+		return nil, fmt.Errorf("failed to read APE items: %w", err)
+	}
+
+	items, err := parseAPEItems(itemsData, int(itemCount))
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse APE items: %w", err)
+	}
+
+	return &APETag{
+		Version:  version,
+		Items:    items,
+		ReadOnly: (flags & apeTagFlagReadOnly) != 0,
+	}, nil
+}
+
+func parseAPEItems(data []byte, count int) ([]APETagItem, error) {
+	items := make([]APETagItem, 0, count)
+	pos := 0
+
+	for i := 0; i < count && pos < len(data); i++ {
+		if pos+8 > len(data) {
+			break
+		}
+
+		valueSize := int(binary.LittleEndian.Uint32(data[pos : pos+4]))
+		itemFlags := binary.LittleEndian.Uint32(data[pos+4 : pos+8])
+		pos += 8
+
+		// Key is null-terminated ASCII (2-255 bytes, case-insensitive)
+		keyEnd := pos
+		for keyEnd < len(data) && data[keyEnd] != 0 {
+			keyEnd++
+		}
+		if keyEnd >= len(data) {
+			break
+		}
+
+		key := string(data[pos:keyEnd])
+		pos = keyEnd + 1
+
+		if pos+valueSize > len(data) {
+			break
+		}
+		value := string(data[pos : pos+valueSize])
+		pos += valueSize
+
+		items = append(items, APETagItem{
+			Key:   key,
+			Value: value,
+			Flags: itemFlags,
+		})
+	}
+
+	return items, nil
+}
+
+// WriteAPETags writes APEv2 tags to the end of a file.
+// If the file already has APEv2 tags, they are replaced.
+// The tag is written with both header and footer.
+func WriteAPETags(filePath string, tag *APETag) error {
+	existingSize, err := findExistingAPETagSize(filePath)
+	if err != nil {
+		return fmt.Errorf("failed to check existing APE tag: %w", err)
+	}
+
+	tagData, err := marshalAPETag(tag)
+	if err != nil {
+		return fmt.Errorf("failed to marshal APE tag: %w", err)
+	}
+
+	if existingSize > 0 {
+		fi, err := os.Stat(filePath)
+		if err != nil {
+			return fmt.Errorf("failed to stat file: %w", err)
+		}
+		newSize := fi.Size() - int64(existingSize)
+		if err := os.Truncate(filePath, newSize); err != nil {
+			return fmt.Errorf("failed to truncate existing APE tag: %w", err)
+		}
+	}
+
+	f, err := os.OpenFile(filePath, os.O_WRONLY|os.O_APPEND, 0644)
+	if err != nil {
+		return fmt.Errorf("failed to open file for writing: %w", err)
+	}
+	defer f.Close()
+
+	if _, err := f.Write(tagData); err != nil {
+		return fmt.Errorf("failed to write APE tag: %w", err)
+	}
+
+	return nil
+}
+
+// findExistingAPETagSize returns the total size of an existing APE tag
+// (header + items + footer) at the end of the file, or 0 if none exists.
+func findExistingAPETagSize(filePath string) (int64, error) {
+	f, err := os.Open(filePath)
+	if err != nil {
+		return 0, err
+	}
+	defer f.Close()
+
+	fi, err := f.Stat()
+	if err != nil {
+		return 0, err
+	}
+	fileSize := fi.Size()
+
+	offsets := []int64{fileSize - apeTagHeaderSize}
+	if fileSize > apeTagHeaderSize+128 {
+		offsets = append(offsets, fileSize-apeTagHeaderSize-128)
+	}
+
+	for _, offset := range offsets {
+		if offset < 0 {
+			continue
+		}
+		footer := make([]byte, apeTagHeaderSize)
+		if _, err := f.ReadAt(footer, offset); err != nil {
+			continue
+		}
+		if string(footer[0:8]) != apeTagPreamble {
+			continue
+		}
+
+		flags := binary.LittleEndian.Uint32(footer[20:24])
+		if (flags & apeTagFlagHeader) != 0 {
+			continue
+		}
+
+		tagSize := int64(binary.LittleEndian.Uint32(footer[12:16]))
+
+		// Check if there's also a header (tagSize only covers items + footer)
+		hasHeader := (flags & (1 << 31)) != 0 // bit 31 = tag contains header
+		totalSize := tagSize
+		if hasHeader {
+			totalSize += apeTagHeaderSize
+		}
+
+		// Include any trailing data after the footer (e.g. ID3v1 128-byte tag).
+		// When truncating, we must remove the APE tag AND everything after it.
+		trailingBytes := fileSize - (offset + apeTagHeaderSize)
+		totalSize += trailingBytes
+
+		return totalSize, nil
+	}
+
+	return 0, nil
+}
+
+// marshalAPETag serializes an APETag into bytes (header + items + footer).
+func marshalAPETag(tag *APETag) ([]byte, error) {
+	if tag == nil || len(tag.Items) == 0 {
+		return nil, fmt.Errorf("empty APE tag")
+	}
+
+	var itemsData []byte
+	for _, item := range tag.Items {
+		keyBytes := []byte(item.Key)
+		valueBytes := []byte(item.Value)
+
+		// 4 bytes: value size (LE)
+		sizeBuf := make([]byte, 4)
+		binary.LittleEndian.PutUint32(sizeBuf, uint32(len(valueBytes)))
+
+		// 4 bytes: item flags (LE)
+		flagsBuf := make([]byte, 4)
+		binary.LittleEndian.PutUint32(flagsBuf, item.Flags)
+
+		itemsData = append(itemsData, sizeBuf...)
+		itemsData = append(itemsData, flagsBuf...)
+		itemsData = append(itemsData, keyBytes...)
+		itemsData = append(itemsData, 0)
+		itemsData = append(itemsData, valueBytes...)
+	}
+
+	// tagSize = items data + footer (32 bytes)
+	tagSize := uint32(len(itemsData) + apeTagHeaderSize)
+	itemCount := uint32(len(tag.Items))
+
+	version := uint32(apeTagVersion2)
+	if tag.Version != 0 {
+		version = tag.Version
+	}
+
+	// flags: bit 29 = 1 (is header), bit 31 = 1 (contains header)
+	headerFlags := uint32(apeTagFlagHeader | (1 << 31))
+	header := buildAPEHeaderFooter(version, tagSize, itemCount, headerFlags)
+
+	// flags: bit 29 = 0 (is footer), bit 31 = 1 (contains header)
+	footerFlags := uint32(1 << 31)
+	footer := buildAPEHeaderFooter(version, tagSize, itemCount, footerFlags)
+
+	// Final layout: header + items + footer
+	result := make([]byte, 0, len(header)+len(itemsData)+len(footer))
+	result = append(result, header...)
+	result = append(result, itemsData...)
+	result = append(result, footer...)
+
+	return result, nil
+}
+
+func buildAPEHeaderFooter(version, tagSize, itemCount, flags uint32) []byte {
+	buf := make([]byte, apeTagHeaderSize)
+	copy(buf[0:8], apeTagPreamble)
+	binary.LittleEndian.PutUint32(buf[8:12], version)
+	binary.LittleEndian.PutUint32(buf[12:16], tagSize)
+	binary.LittleEndian.PutUint32(buf[16:20], itemCount)
+	binary.LittleEndian.PutUint32(buf[20:24], flags)
+	// bytes 24-31 are reserved (zeros)
+	return buf
+}
+
+// APETagToAudioMetadata converts an APETag to our unified AudioMetadata struct.
+func APETagToAudioMetadata(tag *APETag) *AudioMetadata {
+	if tag == nil {
+		return nil
+	}
+
+	metadata := &AudioMetadata{}
+	for _, item := range tag.Items {
+		key := strings.ToUpper(strings.TrimSpace(item.Key))
+		value := strings.TrimSpace(item.Value)
+		if value == "" {
+			continue
+		}
+
+		switch key {
+		case "TITLE":
+			metadata.Title = value
+		case "ARTIST":
+			metadata.Artist = value
+		case "ALBUM":
+			metadata.Album = value
+		case "ALBUMARTIST", "ALBUM ARTIST":
+			metadata.AlbumArtist = value
+		case "GENRE":
+			metadata.Genre = value
+		case "YEAR":
+			metadata.Year = value
+		case "DATE":
+			metadata.Date = value
+		case "TRACK", "TRACKNUMBER":
+			metadata.TrackNumber, metadata.TotalTracks = parseIndexPair(value)
+		case "DISC", "DISCNUMBER":
+			metadata.DiscNumber, metadata.TotalDiscs = parseIndexPair(value)
+		case "ISRC":
+			metadata.ISRC = value
+		case "LYRICS", "UNSYNCEDLYRICS":
+			if metadata.Lyrics == "" {
+				metadata.Lyrics = value
+			}
+		case "LABEL", "PUBLISHER":
+			metadata.Label = value
+		case "COPYRIGHT":
+			metadata.Copyright = value
+		case "COMPOSER":
+			metadata.Composer = value
+		case "COMMENT":
+			metadata.Comment = value
+		case "REPLAYGAIN_TRACK_GAIN":
+			metadata.ReplayGainTrackGain = value
+		case "REPLAYGAIN_TRACK_PEAK":
+			metadata.ReplayGainTrackPeak = value
+		case "REPLAYGAIN_ALBUM_GAIN":
+			metadata.ReplayGainAlbumGain = value
+		case "REPLAYGAIN_ALBUM_PEAK":
+			metadata.ReplayGainAlbumPeak = value
+		}
+	}
+
+	return metadata
+}
+
+// AudioMetadataToAPEItems converts metadata fields to APE tag items.
+func AudioMetadataToAPEItems(metadata *AudioMetadata) []APETagItem {
+	if metadata == nil {
+		return nil
+	}
+
+	var items []APETagItem
+	addItem := func(key, value string) {
+		if value != "" {
+			items = append(items, APETagItem{Key: key, Value: value})
+		}
+	}
+
+	addItem("Title", metadata.Title)
+	addItem("Artist", metadata.Artist)
+	addItem("Album", metadata.Album)
+	addItem("Album Artist", metadata.AlbumArtist)
+	addItem("Genre", metadata.Genre)
+	if metadata.Date != "" {
+		addItem("Year", metadata.Date)
+	} else if metadata.Year != "" {
+		addItem("Year", metadata.Year)
+	}
+	if metadata.TrackNumber > 0 {
+		addItem("Track", formatIndexValue(metadata.TrackNumber, metadata.TotalTracks))
+	}
+	if metadata.DiscNumber > 0 {
+		addItem("Disc", formatIndexValue(metadata.DiscNumber, metadata.TotalDiscs))
+	}
+	addItem("ISRC", metadata.ISRC)
+	addItem("Lyrics", metadata.Lyrics)
+	addItem("Label", metadata.Label)
+	addItem("Copyright", metadata.Copyright)
+	addItem("Composer", metadata.Composer)
+	addItem("Comment", metadata.Comment)
+	addItem("REPLAYGAIN_TRACK_GAIN", metadata.ReplayGainTrackGain)
+	addItem("REPLAYGAIN_TRACK_PEAK", metadata.ReplayGainTrackPeak)
+	addItem("REPLAYGAIN_ALBUM_GAIN", metadata.ReplayGainAlbumGain)
+	addItem("REPLAYGAIN_ALBUM_PEAK", metadata.ReplayGainAlbumPeak)
+
+	return items
+}
+
+// apeKeysFromFields builds a set of upper-case APE tag keys corresponding to
+// the metadata fields map sent by the editor.  This is used during merge to
+// ensure that even empty (cleared) fields override old values.
+func apeKeysFromFields(fields map[string]string) map[string]struct{} {
+	mapping := map[string]string{
+		"title":                 "TITLE",
+		"artist":                "ARTIST",
+		"album":                 "ALBUM",
+		"album_artist":          "ALBUM ARTIST",
+		"date":                  "DATE",
+		"genre":                 "GENRE",
+		"track_number":          "TRACK",
+		"disc_number":           "DISC",
+		"isrc":                  "ISRC",
+		"lyrics":                "LYRICS",
+		"label":                 "LABEL",
+		"copyright":             "COPYRIGHT",
+		"composer":              "COMPOSER",
+		"comment":               "COMMENT",
+		"replaygain_track_gain": "REPLAYGAIN_TRACK_GAIN",
+		"replaygain_track_peak": "REPLAYGAIN_TRACK_PEAK",
+		"replaygain_album_gain": "REPLAYGAIN_ALBUM_GAIN",
+		"replaygain_album_peak": "REPLAYGAIN_ALBUM_PEAK",
+	}
+	result := make(map[string]struct{})
+	for fk, apeKey := range mapping {
+		if _, present := fields[fk]; present {
+			result[strings.ToUpper(apeKey)] = struct{}{}
+		}
+	}
+	// Some fields have reader aliases that must also be cleared when the
+	// canonical key is updated (e.g. DATE writer ↔ DATE/YEAR reader,
+	// DISC ↔ DISCNUMBER, TRACK ↔ TRACKNUMBER, "ALBUM ARTIST" ↔ ALBUMARTIST,
+	// LABEL ↔ PUBLISHER, LYRICS ↔ UNSYNCEDLYRICS).
+	if _, present := fields["date"]; present {
+		result["DATE"] = struct{}{}
+	}
+	if _, present := fields["disc_number"]; present {
+		result["DISCNUMBER"] = struct{}{}
+	}
+	if _, present := fields["disc_total"]; present {
+		result["DISCNUMBER"] = struct{}{}
+	}
+	if _, present := fields["track_number"]; present {
+		result["TRACKNUMBER"] = struct{}{}
+	}
+	if _, present := fields["track_total"]; present {
+		result["TRACKNUMBER"] = struct{}{}
+	}
+	if _, present := fields["album_artist"]; present {
+		result["ALBUMARTIST"] = struct{}{}
+	}
+	if _, present := fields["label"]; present {
+		result["PUBLISHER"] = struct{}{}
+	}
+	if _, present := fields["lyrics"]; present {
+		result["UNSYNCEDLYRICS"] = struct{}{}
+	}
+	return result
+}
+
+// MergeAPEItems overlays newItems on top of existing items.
+// For each new item, if a matching key exists (case-insensitive) in existing,
+// it is replaced. New keys are appended. Existing items whose keys are NOT
+// in newItems are preserved (cover art, ReplayGain, custom tags, etc.).
+//
+// overrideKeys is an optional set of upper-case keys that should be removed
+// from existing even if they do not appear in newItems.  This handles field
+// deletion: the caller sends an empty value which is not serialized into
+// newItems, but the old value must still be dropped.
+func MergeAPEItems(existing, newItems []APETagItem, overrideKeys map[string]struct{}) []APETagItem {
+	// Build a set of keys being updated (upper-case for case-insensitive match)
+	combined := make(map[string]struct{}, len(newItems)+len(overrideKeys))
+	for k := range overrideKeys {
+		combined[strings.ToUpper(k)] = struct{}{}
+	}
+	for _, item := range newItems {
+		combined[strings.ToUpper(item.Key)] = struct{}{}
+	}
+
+	var merged []APETagItem
+	for _, item := range existing {
+		if _, overwritten := combined[strings.ToUpper(item.Key)]; !overwritten {
+			merged = append(merged, item)
+		}
+	}
+
+	merged = append(merged, newItems...)
+
+	return merged
+}
+
+// ReadAPETagsFromReader reads APEv2 tags from an io.ReaderAt + size.
+// This is useful for reading APE tags from files opened via SAF or other abstractions.
+func ReadAPETagsFromReader(r io.ReaderAt, fileSize int64) (*APETag, error) {
+	if fileSize < apeTagHeaderSize {
+		return nil, fmt.Errorf("file too small for APE tag")
+	}
+
+	// Try footer at end of file
+	footer := make([]byte, apeTagHeaderSize)
+	if _, err := r.ReadAt(footer, fileSize-apeTagHeaderSize); err != nil {
+		return nil, fmt.Errorf("failed to read APE footer: %w", err)
+	}
+
+	if string(footer[0:8]) == apeTagPreamble {
+		tag, err := parseAPETagFromFooter(r, fileSize, fileSize-apeTagHeaderSize, footer)
+		if err == nil {
+			return tag, nil
+		}
+	}
+
+	// Retry: skip ID3v1 tag (128 bytes)
+	if fileSize > apeTagHeaderSize+128 {
+		offset := fileSize - apeTagHeaderSize - 128
+		if _, err := r.ReadAt(footer, offset); err == nil {
+			if string(footer[0:8]) == apeTagPreamble {
+				tag, err := parseAPETagFromFooter(r, fileSize, offset, footer)
+				if err == nil {
+					return tag, nil
+				}
+			}
+		}
+	}
+
+	return nil, fmt.Errorf("no APEv2 tag found")
+}
+
+func parseAPETagFromFooter(r io.ReaderAt, fileSize, footerOffset int64, footer []byte) (*APETag, error) {
+	version := binary.LittleEndian.Uint32(footer[8:12])
+	tagSize := binary.LittleEndian.Uint32(footer[12:16])
+	itemCount := binary.LittleEndian.Uint32(footer[16:20])
+	flags := binary.LittleEndian.Uint32(footer[20:24])
+
+	if version != apeTagVersion2 && version != 1000 {
+		return nil, fmt.Errorf("unsupported APE tag version: %d", version)
+	}
+	if tagSize < apeTagHeaderSize {
+		return nil, fmt.Errorf("APE tag size too small: %d", tagSize)
+	}
+	if itemCount > 1000 {
+		return nil, fmt.Errorf("APE tag item count too large: %d", itemCount)
+	}
+	if (flags & apeTagFlagHeader) != 0 {
+		return nil, fmt.Errorf("expected footer, found header")
+	}
+
+	itemsSize := int64(tagSize) - apeTagHeaderSize
+	itemsOffset := footerOffset - itemsSize
+	if itemsOffset < 0 {
+		return nil, fmt.Errorf("APE items extend before file start")
+	}
+
+	itemsData := make([]byte, itemsSize)
+	if _, err := r.ReadAt(itemsData, itemsOffset); err != nil {
+		return nil, fmt.Errorf("failed to read APE items: %w", err)
+	}
+
+	items, err := parseAPEItems(itemsData, int(itemCount))
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse APE items: %w", err)
+	}
+
+	return &APETag{
+		Version:  version,
+		Items:    items,
+		ReadOnly: (flags & apeTagFlagReadOnly) != 0,
+	}, nil
+}

go_backend/audio_metadata_cache_test.go

@@ -0,0 +1,34 @@
+package gobackend
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestResolveLibraryCoverCacheKeyUsesExplicitKey(t *testing.T) {
+	t.Parallel()
+
+	const explicitKey = "content://media/external/audio/media/42|123456"
+	got := resolveLibraryCoverCacheKey("/tmp/saf_random.flac", explicitKey)
+	if got != explicitKey {
+		t.Fatalf("expected explicit cache key %q, got %q", explicitKey, got)
+	}
+}
+
+func TestResolveLibraryCoverCacheKeyUsesFilePathAndStatWhenNoExplicitKey(t *testing.T) {
+	t.Parallel()
+
+	tempFile, err := os.CreateTemp("", "cover-cache-*.flac")
+	if err != nil {
+		t.Fatalf("CreateTemp failed: %v", err)
+	}
+	tempPath := tempFile.Name()
+	tempFile.Close()
+	defer os.Remove(tempPath)
+
+	got := resolveLibraryCoverCacheKey(tempPath, "")
+	if !strings.HasPrefix(got, tempPath+"|") {
+		t.Fatalf("expected stat-based cache key to start with %q, got %q", tempPath+"|", got)
+	}
+}

go_backend/audio_metadata_mp3_test.go

@@ -0,0 +1,133 @@
+package gobackend
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func ffmpegCommand(args ...string) *exec.Cmd {
+	if ffmpegPath, err := exec.LookPath("ffmpeg"); err == nil {
+		return exec.Command(ffmpegPath, args...)
+	}
+	return exec.Command("ffmpeg", args...)
+}
+
+func runFFmpegTestCommand(t *testing.T, args ...string) {
+	t.Helper()
+	cmd := ffmpegCommand(args...)
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("ffmpeg failed: %v\n%s", err, string(output))
+	}
+}
+
+func TestExtractLyricsReadsMp3AfterCoverEmbed(t *testing.T) {
+	if _, err := exec.LookPath("ffmpeg"); err != nil {
+		t.Skip("ffmpeg not available")
+	}
+
+	tempDir := t.TempDir()
+	sourceFlac := filepath.Join(tempDir, "source.flac")
+	baseMp3 := filepath.Join(tempDir, "base.mp3")
+	finalMp3 := filepath.Join(tempDir, "final.mp3")
+	coverPath := filepath.Join(tempDir, "cover.jpg")
+	lyrics := "[ti:Test Song]\n[ar:Test Artist]\n[00:00.00]Hello from embedded lyrics"
+
+	runFFmpegTestCommand(
+		t,
+		"-y",
+		"-f",
+		"lavfi",
+		"-i",
+		"sine=frequency=440:duration=1",
+		"-c:a",
+		"flac",
+		sourceFlac,
+	)
+
+	runFFmpegTestCommand(
+		t,
+		"-y",
+		"-f",
+		"lavfi",
+		"-i",
+		"color=c=red:s=32x32:d=1",
+		"-frames:v",
+		"1",
+		coverPath,
+	)
+
+	runFFmpegTestCommand(
+		t,
+		"-y",
+		"-i",
+		sourceFlac,
+		"-b:a",
+		"320k",
+		"-metadata",
+		"title=Test Song",
+		"-metadata",
+		"artist=Test Artist",
+		"-metadata",
+		"lyrics="+lyrics,
+		baseMp3,
+	)
+
+	runFFmpegTestCommand(
+		t,
+		"-y",
+		"-i",
+		baseMp3,
+		"-i",
+		coverPath,
+		"-map",
+		"0:a",
+		"-map_metadata",
+		"-1",
+		"-map",
+		"1:0",
+		"-c:v:0",
+		"copy",
+		"-id3v2_version",
+		"3",
+		"-metadata",
+		"title=Test Song",
+		"-metadata",
+		"artist=Test Artist",
+		"-metadata",
+		"lyrics="+lyrics,
+		"-metadata:s:v",
+		"title=Album cover",
+		"-metadata:s:v",
+		"comment=Cover (front)",
+		"-c:a",
+		"copy",
+		finalMp3,
+	)
+
+	meta, err := ReadID3Tags(finalMp3)
+	if err != nil {
+		t.Fatalf("ReadID3Tags failed: %v", err)
+	}
+	if meta == nil {
+		t.Fatalf("ReadID3Tags returned nil metadata")
+	}
+
+	embeddedLyrics, err := ExtractLyrics(finalMp3)
+	if err != nil {
+		t.Fatalf("ExtractLyrics failed: %v (metadata=%+v)", err, meta)
+	}
+	if !strings.Contains(embeddedLyrics, "Hello from embedded lyrics") {
+		t.Fatalf("embedded lyrics missing, got %q (metadata=%+v)", embeddedLyrics, meta)
+	}
+	if !strings.Contains(meta.Lyrics, "Hello from embedded lyrics") {
+		t.Fatalf("ReadID3Tags lyrics missing, got %+v", meta)
+	}
+
+	if _, err := os.Stat(finalMp3); err != nil {
+		t.Fatalf("expected final mp3 to exist: %v", err)
+	}
+}

go_backend/cover.go

@@ -17,6 +17,8 @@ const (
 // Deezer CDN supports these sizes: 56, 250, 500, 1000, 1400, 1800
 var deezerSizeRegex = regexp.MustCompile(`/(\d+)x(\d+)-\d+-\d+-\d+-\d+\.jpg$`)
 
+var tidalSizeRegex = regexp.MustCompile(`/\d+x\d+\.jpg$`)
+
 func convertSmallToMedium(imageURL string) string {
 	if strings.Contains(imageURL, spotifySize300) {
 		return strings.Replace(imageURL, spotifySize300, spotifySize640, 1)
@@ -40,7 +42,6 @@ func downloadCoverToMemory(coverURL string, maxQuality bool) ([]byte, error) {
 		maxURL := upgradeToMaxQuality(downloadURL)
 		if maxURL != downloadURL {
 			downloadURL = maxURL
-			// Log already printed by upgradeToMaxQuality for Deezer
 			if strings.Contains(coverURL, "scdn.co") || strings.Contains(coverURL, "spotifycdn") {
 				GoLog("[Cover] Spotify: upgraded to max resolution (~2000x2000)")
 			}
@@ -86,16 +87,22 @@ func downloadCoverToMemory(coverURL string, maxQuality bool) ([]byte, error) {
 }
 
 func upgradeToMaxQuality(coverURL string) string {
-	// Spotify CDN upgrade
 	if strings.Contains(coverURL, spotifySize640) {
 		return strings.Replace(coverURL, spotifySize640, spotifySizeMax, 1)
 	}
 
-	// Deezer CDN upgrade
 	if strings.Contains(coverURL, "cdn-images.dzcdn.net") {
 		return upgradeDeezerCover(coverURL)
 	}
 
+	if strings.Contains(coverURL, "resources.tidal.com") {
+		return upgradeTidalCover(coverURL)
+	}
+
+	if strings.Contains(coverURL, "static.qobuz.com") {
+		return upgradeQobuzCover(coverURL)
+	}
+
 	return coverURL
 }
 
@@ -104,7 +111,6 @@ func upgradeDeezerCover(coverURL string) string {
 		return coverURL
 	}
 
-	// Replace any size pattern with 1800x1800
 	upgraded := deezerSizeRegex.ReplaceAllString(coverURL, "/1800x1800-000000-80-0-0.jpg")
 	if upgraded != coverURL {
 		GoLog("[Cover] Deezer: upgraded to 1800x1800")
@@ -112,12 +118,35 @@ func upgradeDeezerCover(coverURL string) string {
 	return upgraded
 }
 
+func upgradeTidalCover(coverURL string) string {
+	if !strings.Contains(coverURL, "resources.tidal.com") {
+		return coverURL
+	}
+
+	upgraded := tidalSizeRegex.ReplaceAllString(coverURL, "/origin.jpg")
+	if upgraded != coverURL {
+		GoLog("[Cover] Tidal: upgraded to origin resolution")
+	}
+	return upgraded
+}
+
+func upgradeQobuzCover(coverURL string) string {
+	if !strings.Contains(coverURL, "static.qobuz.com") {
+		return coverURL
+	}
+
+	upgraded := qobuzImageSizeRe.ReplaceAllString(coverURL, "_max.jpg")
+	if upgraded != coverURL {
+		GoLog("[Cover] Qobuz: upgraded to max resolution")
+	}
+	return upgraded
+}
+
 func GetCoverFromSpotify(imageURL string, maxQuality bool) string {
 	if imageURL == "" {
 		return ""
 	}
 
-	// Always upgrade small to medium first
 	result := convertSmallToMedium(imageURL)
 
 	if maxQuality {

go_backend/cue_parser.go

@@ -0,0 +1,565 @@
+package gobackend
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+type CueSheet struct {
+	Performer string     `json:"performer"`
+	Title     string     `json:"title"`
+	FileName  string     `json:"file_name"`
+	FileType  string     `json:"file_type"` // WAVE, FLAC, MP3, AIFF, etc.
+	Genre     string     `json:"genre,omitempty"`
+	Date      string     `json:"date,omitempty"`
+	Comment   string     `json:"comment,omitempty"`
+	Composer  string     `json:"composer,omitempty"`
+	Tracks    []CueTrack `json:"tracks"`
+}
+
+type CueTrack struct {
+	Number    int     `json:"number"`
+	Title     string  `json:"title"`
+	Performer string  `json:"performer"`
+	ISRC      string  `json:"isrc,omitempty"`
+	Composer  string  `json:"composer,omitempty"`
+	StartTime float64 `json:"start_time"` // INDEX 01 in seconds
+	PreGap    float64 `json:"pre_gap"`    // INDEX 00 in seconds (or -1 if not present)
+}
+
+type CueSplitInfo struct {
+	CuePath   string          `json:"cue_path"`
+	AudioPath string          `json:"audio_path"`
+	Album     string          `json:"album"`
+	Artist    string          `json:"artist"`
+	Genre     string          `json:"genre,omitempty"`
+	Date      string          `json:"date,omitempty"`
+	Tracks    []CueSplitTrack `json:"tracks"`
+}
+
+type CueSplitTrack struct {
+	Number   int     `json:"number"`
+	Title    string  `json:"title"`
+	Artist   string  `json:"artist"`
+	ISRC     string  `json:"isrc,omitempty"`
+	Composer string  `json:"composer,omitempty"`
+	StartSec float64 `json:"start_sec"`
+	EndSec   float64 `json:"end_sec"` // -1 means until end of file
+}
+
+var (
+	reRemCommand = regexp.MustCompile(`^REM\s+(\S+)\s+(.+)$`)
+	reQuoted     = regexp.MustCompile(`"([^"]*)"`)
+)
+
+func ParseCueFile(cuePath string) (*CueSheet, error) {
+	f, err := os.Open(cuePath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open cue file: %w", err)
+	}
+	defer f.Close()
+
+	sheet := &CueSheet{}
+	var currentTrack *CueTrack
+
+	scanner := bufio.NewScanner(f)
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+
+		if strings.HasPrefix(line, "\xef\xbb\xbf") {
+			line = strings.TrimPrefix(line, "\xef\xbb\xbf")
+			line = strings.TrimSpace(line)
+		}
+
+		upper := strings.ToUpper(line)
+
+		if strings.HasPrefix(upper, "REM ") {
+			matches := reRemCommand.FindStringSubmatch(line)
+			if len(matches) == 3 {
+				key := strings.ToUpper(matches[1])
+				value := unquoteCue(matches[2])
+				switch key {
+				case "GENRE":
+					sheet.Genre = value
+				case "DATE":
+					sheet.Date = value
+				case "COMMENT":
+					sheet.Comment = value
+				case "COMPOSER":
+					if currentTrack != nil {
+						currentTrack.Composer = value
+					} else {
+						sheet.Composer = value
+					}
+				}
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "PERFORMER ") {
+			value := unquoteCue(line[len("PERFORMER "):])
+			if currentTrack != nil {
+				currentTrack.Performer = value
+			} else {
+				sheet.Performer = value
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "TITLE ") {
+			value := unquoteCue(line[len("TITLE "):])
+			if currentTrack != nil {
+				currentTrack.Title = value
+			} else {
+				sheet.Title = value
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "FILE ") {
+			rest := line[len("FILE "):]
+			fname, ftype := parseCueFileLine(rest)
+			sheet.FileName = fname
+			sheet.FileType = ftype
+			continue
+		}
+
+		if strings.HasPrefix(upper, "TRACK ") {
+			if currentTrack != nil {
+				sheet.Tracks = append(sheet.Tracks, *currentTrack)
+			}
+
+			parts := strings.Fields(line)
+			trackNum := 0
+			if len(parts) >= 2 {
+				trackNum, _ = strconv.Atoi(parts[1])
+			}
+
+			currentTrack = &CueTrack{
+				Number: trackNum,
+				PreGap: -1,
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "INDEX ") && currentTrack != nil {
+			parts := strings.Fields(line)
+			if len(parts) >= 3 {
+				indexNum, _ := strconv.Atoi(parts[1])
+				timeSec := parseCueTimestamp(parts[2])
+				switch indexNum {
+				case 0:
+					currentTrack.PreGap = timeSec
+				case 1:
+					currentTrack.StartTime = timeSec
+				}
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "ISRC ") && currentTrack != nil {
+			currentTrack.ISRC = strings.TrimSpace(line[len("ISRC "):])
+			continue
+		}
+
+		if strings.HasPrefix(upper, "SONGWRITER ") {
+			value := unquoteCue(line[len("SONGWRITER "):])
+			if currentTrack != nil {
+				currentTrack.Composer = value
+			} else {
+				sheet.Composer = value
+			}
+			continue
+		}
+	}
+
+	if currentTrack != nil {
+		sheet.Tracks = append(sheet.Tracks, *currentTrack)
+	}
+
+	if err := scanner.Err(); err != nil {
+		return nil, fmt.Errorf("error reading cue file: %w", err)
+	}
+
+	if len(sheet.Tracks) == 0 {
+		return nil, fmt.Errorf("no tracks found in cue file")
+	}
+
+	return sheet, nil
+}
+
+func parseCueTimestamp(ts string) float64 {
+	parts := strings.Split(ts, ":")
+	if len(parts) != 3 {
+		return 0
+	}
+
+	minutes, _ := strconv.Atoi(parts[0])
+	seconds, _ := strconv.Atoi(parts[1])
+	frames, _ := strconv.Atoi(parts[2])
+
+	return float64(minutes)*60 + float64(seconds) + float64(frames)/75.0
+}
+
+func formatCueTimestamp(seconds float64) string {
+	if seconds < 0 {
+		return "0"
+	}
+	hours := int(seconds) / 3600
+	mins := (int(seconds) % 3600) / 60
+	secs := seconds - float64(hours*3600) - float64(mins*60)
+	return fmt.Sprintf("%02d:%02d:%06.3f", hours, mins, secs)
+}
+
+func unquoteCue(s string) string {
+	s = strings.TrimSpace(s)
+	if matches := reQuoted.FindStringSubmatch(s); len(matches) == 2 {
+		return matches[1]
+	}
+	return s
+}
+
+func parseCueFileLine(rest string) (string, string) {
+	rest = strings.TrimSpace(rest)
+
+	var filename, ftype string
+
+	if strings.HasPrefix(rest, "\"") {
+		endQuote := strings.Index(rest[1:], "\"")
+		if endQuote >= 0 {
+			filename = rest[1 : endQuote+1]
+			remaining := strings.TrimSpace(rest[endQuote+2:])
+			ftype = remaining
+		} else {
+			filename = rest
+		}
+	} else {
+		parts := strings.Fields(rest)
+		if len(parts) >= 2 {
+			ftype = parts[len(parts)-1]
+			filename = strings.Join(parts[:len(parts)-1], " ")
+		} else if len(parts) == 1 {
+			filename = parts[0]
+		}
+	}
+
+	return filename, strings.TrimSpace(ftype)
+}
+
+func ResolveCueAudioPath(cuePath string, cueFileName string) string {
+	cueDir := filepath.Dir(cuePath)
+
+	candidate := filepath.Join(cueDir, cueFileName)
+	if _, err := os.Stat(candidate); err == nil {
+		return candidate
+	}
+
+	baseName := strings.TrimSuffix(cueFileName, filepath.Ext(cueFileName))
+	commonExts := []string{".flac", ".wav", ".ape", ".mp3", ".ogg", ".wv", ".m4a"}
+	for _, ext := range commonExts {
+		candidate = filepath.Join(cueDir, baseName+ext)
+		if _, err := os.Stat(candidate); err == nil {
+			return candidate
+		}
+		candidate = filepath.Join(cueDir, baseName+strings.ToUpper(ext))
+		if _, err := os.Stat(candidate); err == nil {
+			return candidate
+		}
+	}
+
+	cueBase := strings.TrimSuffix(filepath.Base(cuePath), filepath.Ext(cuePath))
+	for _, ext := range commonExts {
+		candidate = filepath.Join(cueDir, cueBase+ext)
+		if _, err := os.Stat(candidate); err == nil {
+			return candidate
+		}
+	}
+
+	entries, err := os.ReadDir(cueDir)
+	if err == nil {
+		audioExts := map[string]bool{
+			".flac": true, ".wav": true, ".ape": true, ".mp3": true,
+			".ogg": true, ".wv": true, ".m4a": true, ".aiff": true,
+		}
+		var audioFiles []string
+		for _, entry := range entries {
+			if entry.IsDir() {
+				continue
+			}
+			ext := strings.ToLower(filepath.Ext(entry.Name()))
+			if audioExts[ext] {
+				audioFiles = append(audioFiles, filepath.Join(cueDir, entry.Name()))
+			}
+		}
+		if len(audioFiles) == 1 {
+			return audioFiles[0]
+		}
+	}
+
+	return ""
+}
+
+func BuildCueSplitInfo(cuePath string, sheet *CueSheet, audioDir string) (*CueSplitInfo, error) {
+	resolveDir := cuePath
+	if audioDir != "" {
+		resolveDir = filepath.Join(audioDir, filepath.Base(cuePath))
+	}
+	audioPath := ResolveCueAudioPath(resolveDir, sheet.FileName)
+	if audioPath == "" {
+		return nil, fmt.Errorf("audio file not found for cue sheet: %s (referenced: %s)", cuePath, sheet.FileName)
+	}
+
+	info := &CueSplitInfo{
+		CuePath:   cuePath,
+		AudioPath: audioPath,
+		Album:     sheet.Title,
+		Artist:    sheet.Performer,
+		Genre:     sheet.Genre,
+		Date:      sheet.Date,
+	}
+
+	for i, track := range sheet.Tracks {
+		performer := track.Performer
+		if performer == "" {
+			performer = sheet.Performer
+		}
+
+		composer := track.Composer
+		if composer == "" {
+			composer = sheet.Composer
+		}
+
+		endSec := float64(-1)
+		if i+1 < len(sheet.Tracks) {
+			nextTrack := sheet.Tracks[i+1]
+			if nextTrack.PreGap >= 0 {
+				endSec = nextTrack.PreGap
+			} else {
+				endSec = nextTrack.StartTime
+			}
+		}
+
+		info.Tracks = append(info.Tracks, CueSplitTrack{
+			Number:   track.Number,
+			Title:    track.Title,
+			Artist:   performer,
+			ISRC:     track.ISRC,
+			Composer: composer,
+			StartSec: track.StartTime,
+			EndSec:   endSec,
+		})
+	}
+
+	return info, nil
+}
+
+func ParseCueFileJSON(cuePath string, audioDir string) (string, error) {
+	sheet, err := ParseCueFile(cuePath)
+	if err != nil {
+		return "", fmt.Errorf("failed to parse cue file: %w", err)
+	}
+
+	info, err := BuildCueSplitInfo(cuePath, sheet, audioDir)
+	if err != nil {
+		return "", err
+	}
+
+	jsonBytes, err := json.Marshal(info)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal cue split info: %w", err)
+	}
+
+	return string(jsonBytes), nil
+}
+
+func ScanCueFileForLibrary(cuePath string, scanTime string) ([]LibraryScanResult, error) {
+	sheet, err := ParseCueFile(cuePath)
+	if err != nil {
+		return nil, err
+	}
+	audioPath, err := resolveCueAudioPathForLibrary(cuePath, sheet, "")
+	if err != nil {
+		return nil, err
+	}
+	return scanCueSheetForLibrary(cuePath, sheet, audioPath, "", 0, "", scanTime)
+}
+
+func ScanCueFileForLibraryExt(cuePath, audioDir, virtualPathPrefix string, fileModTime int64, scanTime string) ([]LibraryScanResult, error) {
+	return ScanCueFileForLibraryExtWithCoverCacheKey(
+		cuePath,
+		audioDir,
+		virtualPathPrefix,
+		fileModTime,
+		"",
+		scanTime,
+	)
+}
+
+func ScanCueFileForLibraryExtWithCoverCacheKey(cuePath, audioDir, virtualPathPrefix string, fileModTime int64, coverCacheKey, scanTime string) ([]LibraryScanResult, error) {
+	sheet, err := ParseCueFile(cuePath)
+	if err != nil {
+		return nil, err
+	}
+	audioPath, err := resolveCueAudioPathForLibrary(cuePath, sheet, audioDir)
+	if err != nil {
+		return nil, err
+	}
+	return scanCueSheetForLibrary(
+		cuePath,
+		sheet,
+		audioPath,
+		virtualPathPrefix,
+		fileModTime,
+		coverCacheKey,
+		scanTime,
+	)
+}
+
+func resolveCueAudioPathForLibrary(cuePath string, sheet *CueSheet, audioDir string) (string, error) {
+	if sheet == nil {
+		return "", fmt.Errorf("cue sheet is nil for %s", cuePath)
+	}
+	resolveBase := cuePath
+	if audioDir != "" {
+		resolveBase = filepath.Join(audioDir, filepath.Base(cuePath))
+	}
+	audioPath := ResolveCueAudioPath(resolveBase, sheet.FileName)
+	if audioPath == "" {
+		return "", fmt.Errorf("audio file not found for cue: %s (referenced: %s)", cuePath, sheet.FileName)
+	}
+	return audioPath, nil
+}
+
+func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualPathPrefix string, fileModTime int64, coverCacheKey, scanTime string) ([]LibraryScanResult, error) {
+	if sheet == nil {
+		return nil, fmt.Errorf("cue sheet is nil for %s", cuePath)
+	}
+
+	var bitDepth, sampleRate int
+	var totalDurationSec float64
+	audioExt := strings.ToLower(filepath.Ext(audioPath))
+	switch audioExt {
+	case ".flac":
+		quality, qErr := GetAudioQuality(audioPath)
+		if qErr == nil {
+			bitDepth = quality.BitDepth
+			sampleRate = quality.SampleRate
+			if quality.SampleRate > 0 && quality.TotalSamples > 0 {
+				totalDurationSec = float64(quality.TotalSamples) / float64(quality.SampleRate)
+			}
+		}
+	case ".mp3":
+		quality, qErr := GetMP3Quality(audioPath)
+		if qErr == nil {
+			sampleRate = quality.SampleRate
+			totalDurationSec = float64(quality.Duration)
+		}
+	}
+
+	var coverPath string
+	libraryCoverCacheMu.RLock()
+	coverCacheDir := libraryCoverCacheDir
+	libraryCoverCacheMu.RUnlock()
+	if coverCacheDir != "" {
+		cp, err := SaveCoverToCacheWithHintAndKey(
+			audioPath,
+			"",
+			coverCacheDir,
+			coverCacheKey,
+		)
+		if err == nil && cp != "" {
+			coverPath = cp
+		}
+	}
+
+	pathBase := cuePath
+	if virtualPathPrefix != "" {
+		pathBase = virtualPathPrefix
+	}
+
+	modTime := fileModTime
+	if modTime <= 0 {
+		if info, err := os.Stat(cuePath); err == nil {
+			modTime = info.ModTime().UnixMilli()
+		}
+	}
+
+	var results []LibraryScanResult
+	for i, track := range sheet.Tracks {
+		performer := track.Performer
+		if performer == "" {
+			performer = sheet.Performer
+		}
+		if performer == "" {
+			performer = "Unknown Artist"
+		}
+
+		title := track.Title
+		if title == "" {
+			title = fmt.Sprintf("Track %02d", track.Number)
+		}
+
+		album := sheet.Title
+		if album == "" {
+			album = "Unknown Album"
+		}
+
+		composer := track.Composer
+		if composer == "" {
+			composer = sheet.Composer
+		}
+
+		var duration int
+		if i+1 < len(sheet.Tracks) {
+			nextStart := sheet.Tracks[i+1].StartTime
+			if sheet.Tracks[i+1].PreGap >= 0 {
+				nextStart = sheet.Tracks[i+1].PreGap
+			}
+			duration = int(nextStart - track.StartTime)
+		} else if totalDurationSec > 0 {
+			duration = int(totalDurationSec - track.StartTime)
+		}
+
+		id := generateLibraryID(fmt.Sprintf("%s#track%d", pathBase, track.Number))
+
+		virtualFilePath := fmt.Sprintf("%s#track%02d", pathBase, track.Number)
+
+		result := LibraryScanResult{
+			ID:          id,
+			TrackName:   title,
+			ArtistName:  performer,
+			AlbumName:   album,
+			AlbumArtist: sheet.Performer,
+			FilePath:    virtualFilePath,
+			CoverPath:   coverPath,
+			ScannedAt:   scanTime,
+			ISRC:        track.ISRC,
+			TrackNumber: track.Number,
+			TotalTracks: len(sheet.Tracks),
+			DiscNumber:  1,
+			TotalDiscs:  1,
+			Duration:    duration,
+			ReleaseDate: sheet.Date,
+			BitDepth:    bitDepth,
+			SampleRate:  sampleRate,
+			Genre:       sheet.Genre,
+			Composer:    composer,
+			Format:      "cue+" + strings.TrimPrefix(audioExt, "."),
+		}
+
+		result.FileModTime = modTime
+
+		results = append(results, result)
+	}
+
+	return results, nil
+}

go_backend/duplicate.go

@@ -10,7 +10,6 @@ import (
 	"time"
 )
 
-// ISRCIndex holds a cached map of ISRC -> file path for fast duplicate checking
 type ISRCIndex struct {
 	index     map[string]string // ISRC (uppercase) -> file path
 	outputDir string
@@ -25,10 +24,7 @@ var (
 	isrcIndexTTL     = 5 * time.Minute
 )
 
-// GetISRCIndex returns or builds an ISRC index for the given directory
-// Uses per-directory mutex to prevent concurrent builds (race condition fix)
 func GetISRCIndex(outputDir string) *ISRCIndex {
-	// Fast path: check cache first
 	isrcIndexCacheMu.RLock()
 	idx, exists := isrcIndexCache[outputDir]
 	isrcIndexCacheMu.RUnlock()
@@ -37,14 +33,11 @@ func GetISRCIndex(outputDir string) *ISRCIndex {
 		return idx
 	}
 
-	// Slow path: need to build index
-	// Use per-directory mutex to prevent multiple goroutines from building simultaneously
 	buildLock, _ := isrcBuildingMu.LoadOrStore(outputDir, &sync.Mutex{})
 	mu := buildLock.(*sync.Mutex)
 	mu.Lock()
 	defer mu.Unlock()
 
-	// Double-check cache after acquiring lock (another goroutine may have built it)
 	isrcIndexCacheMu.RLock()
 	idx, exists = isrcIndexCache[outputDir]
 	isrcIndexCacheMu.RUnlock()
@@ -56,7 +49,6 @@ func GetISRCIndex(outputDir string) *ISRCIndex {
 	return buildISRCIndex(outputDir)
 }
 
-// buildISRCIndex scans a directory and builds a map of ISRC -> file path
 func buildISRCIndex(outputDir string) *ISRCIndex {
 	idx := &ISRCIndex{
 		index:     make(map[string]string),
@@ -91,7 +83,7 @@ func buildISRCIndex(outputDir string) *ISRCIndex {
 		return nil
 	})
 
-	fmt.Printf("[ISRCIndex] Built index for %s: %d files in %v\n", 
+	fmt.Printf("[ISRCIndex] Built index for %s: %d files in %v\n",
 		outputDir, fileCount, time.Since(startTime).Round(time.Millisecond))
 
 	isrcIndexCacheMu.Lock()
@@ -113,7 +105,6 @@ func (idx *ISRCIndex) lookup(isrc string) (string, bool) {
 	return path, exists
 }
 
-// remove deletes an ISRC entry from the index (internal use)
 func (idx *ISRCIndex) remove(isrc string) {
 	if isrc == "" {
 		return
@@ -125,14 +116,11 @@ func (idx *ISRCIndex) remove(isrc string) {
 	delete(idx.index, strings.ToUpper(isrc))
 }
 
-// Lookup checks if an ISRC exists in the index (gomobile compatible)
-// Returns filepath if found, empty string if not found
 func (idx *ISRCIndex) Lookup(isrc string) (string, error) {
 	path, _ := idx.lookup(isrc)
 	return path, nil
 }
 
-// Add adds a new ISRC to the index (call after successful download)
 func (idx *ISRCIndex) Add(isrc, filePath string) {
 	if isrc == "" || filePath == "" {
 		return
@@ -144,15 +132,12 @@ func (idx *ISRCIndex) Add(isrc, filePath string) {
 	idx.index[strings.ToUpper(isrc)] = filePath
 }
 
-// InvalidateCache clears the ISRC index cache for a directory
 func InvalidateISRCCache(outputDir string) {
 	isrcIndexCacheMu.Lock()
 	delete(isrcIndexCache, outputDir)
 	isrcIndexCacheMu.Unlock()
 }
 
-// checkISRCExistsInternal checks if a file with the given ISRC exists (internal use)
-// Uses ISRC index for fast lookup
 func checkISRCExistsInternal(outputDir, isrc string) (string, bool) {
 	if isrc == "" || outputDir == "" {
 		return "", false
@@ -173,13 +158,11 @@ func checkISRCExistsInternal(outputDir, isrc string) (string, bool) {
 	return filePath, true
 }
 
-// CheckISRCExists is the exported version for gomobile (returns string, error)
 func CheckISRCExists(outputDir, isrc string) (string, error) {
 	filepath, _ := checkISRCExistsInternal(outputDir, isrc)
 	return filepath, nil
 }
 
-// CheckFileExists checks if a file with the given name exists
 func CheckFileExists(filePath string) bool {
 	info, err := os.Stat(filePath)
 	if err != nil {
@@ -188,7 +171,6 @@ func CheckFileExists(filePath string) bool {
 	return !info.IsDir() && info.Size() > 0
 }
 
-// FileExistenceResult represents the result of checking if a file exists
 type FileExistenceResult struct {
 	ISRC       string `json:"isrc"`
 	Exists     bool   `json:"exists"`
@@ -249,8 +231,6 @@ func CheckFilesExistParallel(outputDir string, tracksJSON string) (string, error
 	return string(resultJSON), nil
 }
 
-// PreBuildISRCIndex pre-builds the ISRC index for a directory
-// Call this when app starts or when entering album/playlist screen
 func PreBuildISRCIndex(outputDir string) error {
 	if outputDir == "" {
 		return fmt.Errorf("output directory is required")
@@ -260,7 +240,6 @@ func PreBuildISRCIndex(outputDir string) error {
 	return nil
 }
 
-// AddToISRCIndex adds a new file to the ISRC index after successful download
 func AddToISRCIndex(outputDir, isrc, filePath string) {
 	if outputDir == "" || isrc == "" || filePath == "" {
 		return

go_backend/exports_deezer_metadata_test.go

@@ -0,0 +1,59 @@
+package gobackend
+
+import "testing"
+
+func TestBuildDeezerExtendedMetadataResultHandlesNil(t *testing.T) {
+	result := buildDeezerExtendedMetadataResult(nil)
+
+	if result["genre"] != "" {
+		t.Fatalf("expected empty genre, got %q", result["genre"])
+	}
+	if result["label"] != "" {
+		t.Fatalf("expected empty label, got %q", result["label"])
+	}
+	if result["copyright"] != "" {
+		t.Fatalf("expected empty copyright, got %q", result["copyright"])
+	}
+}
+
+func TestBuildDeezerExtendedMetadataResultIncludesCopyright(t *testing.T) {
+	result := buildDeezerExtendedMetadataResult(&AlbumExtendedMetadata{
+		Genre:     "Rock",
+		Label:     "EMI",
+		Copyright: "(C) Queen",
+	})
+
+	if result["genre"] != "Rock" {
+		t.Fatalf("unexpected genre: %q", result["genre"])
+	}
+	if result["label"] != "EMI" {
+		t.Fatalf("unexpected label: %q", result["label"])
+	}
+	if result["copyright"] != "(C) Queen" {
+		t.Fatalf("unexpected copyright: %q", result["copyright"])
+	}
+}
+
+func TestBuildDeezerISRCSearchResultAddsCompatibilityIDs(t *testing.T) {
+	result := buildDeezerISRCSearchResult(&TrackMetadata{
+		SpotifyID:   "deezer:3135556",
+		Name:        "Love Of My Life",
+		Artists:     "Queen",
+		AlbumName:   "A Night at the Opera",
+		ISRC:        "GBUM71029604",
+		ReleaseDate: "1975-11-21",
+	})
+
+	if result["spotify_id"] != "deezer:3135556" {
+		t.Fatalf("unexpected spotify_id: %v", result["spotify_id"])
+	}
+	if result["id"] != "3135556" {
+		t.Fatalf("unexpected id: %v", result["id"])
+	}
+	if result["track_id"] != "3135556" {
+		t.Fatalf("unexpected track_id: %v", result["track_id"])
+	}
+	if result["success"] != true {
+		t.Fatalf("expected success=true, got %v", result["success"])
+	}
+}

go_backend/exports_test.go

@@ -0,0 +1,343 @@
+package gobackend
+
+import "testing"
+
+func TestSetExtensionFallbackProviderIDsJSONEmptyStringResetsDefault(t *testing.T) {
+	original := GetExtensionFallbackProviderIDs()
+	defer SetExtensionFallbackProviderIDs(original)
+
+	SetExtensionFallbackProviderIDs([]string{"custom-ext"})
+
+	if err := SetExtensionFallbackProviderIDsJSON(""); err != nil {
+		t.Fatalf("SetExtensionFallbackProviderIDsJSON returned error: %v", err)
+	}
+
+	if got := GetExtensionFallbackProviderIDs(); got != nil {
+		t.Fatalf("expected nil fallback provider list after reset, got %v", got)
+	}
+}
+
+func TestBuildDownloadSuccessResponsePrefersRequestedAlbumMetadata(t *testing.T) {
+	req := DownloadRequest{
+		TrackName:   "Bonus Track",
+		ArtistName:  "Artist",
+		AlbumName:   "Album (Deluxe)",
+		AlbumArtist: "Artist",
+		ReleaseDate: "2024-01-01",
+		TrackNumber: 14,
+		DiscNumber:  1,
+		ISRC:        "REQ123",
+		CoverURL:    "https://example.com/cover.jpg",
+		Genre:       "Pop",
+		Label:       "Label",
+		Copyright:   "Copyright",
+	}
+
+	result := DownloadResult{
+		Title:       "Bonus Track",
+		Artist:      "Artist",
+		Album:       "Album",
+		ReleaseDate: "2023-12-01",
+		TrackNumber: 2,
+		DiscNumber:  9,
+		ISRC:        "RES456",
+	}
+
+	resp := buildDownloadSuccessResponse(
+		req,
+		result,
+		"tidal",
+		"ok",
+		"/tmp/test.flac",
+		false,
+	)
+
+	if resp.Album != req.AlbumName {
+		t.Fatalf("album = %q, want %q", resp.Album, req.AlbumName)
+	}
+	if resp.ReleaseDate != req.ReleaseDate {
+		t.Fatalf("release date = %q, want %q", resp.ReleaseDate, req.ReleaseDate)
+	}
+	if resp.TrackNumber != req.TrackNumber {
+		t.Fatalf("track number = %d, want %d", resp.TrackNumber, req.TrackNumber)
+	}
+	if resp.DiscNumber != req.DiscNumber {
+		t.Fatalf("disc number = %d, want %d", resp.DiscNumber, req.DiscNumber)
+	}
+	if resp.Artist != result.Artist {
+		t.Fatalf("artist = %q, want provider artist %q", resp.Artist, result.Artist)
+	}
+	if resp.ISRC != result.ISRC {
+		t.Fatalf("isrc = %q, want provider isrc %q", resp.ISRC, result.ISRC)
+	}
+}
+
+func TestPreferredReleaseMetadataPrefersRequestValues(t *testing.T) {
+	album, releaseDate, trackNumber, discNumber := preferredReleaseMetadata(
+		DownloadRequest{
+			AlbumName:   "Album (Deluxe Edition)",
+			ReleaseDate: "2024-01-01",
+			TrackNumber: 13,
+			DiscNumber:  2,
+		},
+		"Album",
+		"2023-01-01",
+		3,
+		1,
+	)
+
+	if album != "Album (Deluxe Edition)" {
+		t.Fatalf("album = %q", album)
+	}
+	if releaseDate != "2024-01-01" {
+		t.Fatalf("release date = %q", releaseDate)
+	}
+	if trackNumber != 13 {
+		t.Fatalf("track number = %d", trackNumber)
+	}
+	if discNumber != 2 {
+		t.Fatalf("disc number = %d", discNumber)
+	}
+}
+
+func TestBuildDownloadSuccessResponsePrefersProviderCoverURL(t *testing.T) {
+	req := DownloadRequest{
+		TrackName:   "Track",
+		ArtistName:  "Artist",
+		AlbumName:   "Album",
+		AlbumArtist: "Artist",
+	}
+
+	result := DownloadResult{
+		Title:    "Track",
+		Artist:   "Artist",
+		Album:    "Album",
+		CoverURL: "https://cdn.qobuz.test/cover.jpg",
+	}
+
+	resp := buildDownloadSuccessResponse(
+		req,
+		result,
+		"qobuz",
+		"ok",
+		"/tmp/test.flac",
+		false,
+	)
+
+	if resp.CoverURL != result.CoverURL {
+		t.Fatalf("cover url = %q, want %q", resp.CoverURL, result.CoverURL)
+	}
+}
+
+func TestBuildDownloadSuccessResponseNormalizesDecryptionDescriptor(t *testing.T) {
+	req := DownloadRequest{
+		TrackName:  "Track",
+		ArtistName: "Artist",
+	}
+
+	result := DownloadResult{
+		Title:         "Track",
+		Artist:        "Artist",
+		DecryptionKey: "00112233",
+	}
+
+	resp := buildDownloadSuccessResponse(
+		req,
+		result,
+		"amazon",
+		"ok",
+		"/tmp/test.m4a",
+		false,
+	)
+
+	if resp.Decryption == nil {
+		t.Fatal("expected decryption descriptor to be present")
+	}
+	if resp.Decryption.Strategy != genericFFmpegMOVDecryptionStrategy {
+		t.Fatalf("strategy = %q", resp.Decryption.Strategy)
+	}
+	if resp.Decryption.Key != result.DecryptionKey {
+		t.Fatalf("key = %q, want %q", resp.Decryption.Key, result.DecryptionKey)
+	}
+}
+
+func TestApplyReEnrichTrackMetadataPreservesExistingReleaseDateWhenCandidateMissing(t *testing.T) {
+	req := reEnrichRequest{
+		SpotifyID:   "spotify-track-id",
+		AlbumName:   "Original Album",
+		ReleaseDate: "2024-01-01",
+		ISRC:        "REQ123",
+	}
+
+	applyReEnrichTrackMetadata(&req, ExtTrackMetadata{
+		AlbumName:   "Resolved Album",
+		ReleaseDate: "",
+		ISRC:        "",
+	})
+
+	if req.ReleaseDate != "2024-01-01" {
+		t.Fatalf("release date = %q, want existing value preserved", req.ReleaseDate)
+	}
+	if req.AlbumName != "Resolved Album" {
+		t.Fatalf("album = %q, want updated album", req.AlbumName)
+	}
+	if req.ISRC != "REQ123" {
+		t.Fatalf("isrc = %q, want existing value preserved", req.ISRC)
+	}
+}
+
+func TestSelectBestReEnrichTrackPrefersCandidateWithReleaseDate(t *testing.T) {
+	req := reEnrichRequest{
+		TrackName:   "Song Title",
+		ArtistName:  "Artist Name",
+		AlbumName:   "Album Name",
+		ReleaseDate: "",
+		DurationMs:  180000,
+	}
+
+	tracks := []ExtTrackMetadata{
+		{
+			ID:          "first",
+			Name:        "Song Title",
+			Artists:     "Artist Name",
+			AlbumName:   "Album Name",
+			DurationMS:  180000,
+			ReleaseDate: "",
+			ProviderID:  "spotify",
+		},
+		{
+			ID:          "second",
+			Name:        "Song Title",
+			Artists:     "Artist Name",
+			AlbumName:   "Album Name",
+			DurationMS:  180000,
+			ReleaseDate: "2024-03-09",
+			ProviderID:  "deezer",
+		},
+	}
+
+	best := selectBestReEnrichTrack(req, tracks)
+	if best == nil {
+		t.Fatal("expected a selected track")
+	}
+	if best.ID != "second" {
+		t.Fatalf("selected track = %q, want candidate with release date", best.ID)
+	}
+}
+
+func TestBuildReEnrichFFmpegMetadataOmitsEmptyFields(t *testing.T) {
+	req := reEnrichRequest{
+		TrackName:   "Song",
+		ArtistName:  "Artist",
+		AlbumName:   "Album",
+		AlbumArtist: "",
+		ReleaseDate: "",
+		TrackNumber: 0,
+		DiscNumber:  0,
+		ISRC:        "",
+		Genre:       "",
+		Label:       "",
+		Copyright:   "",
+	}
+
+	metadata := buildReEnrichFFmpegMetadata(&req, "")
+
+	if metadata["TITLE"] != "Song" {
+		t.Fatalf("title = %q", metadata["TITLE"])
+	}
+	if metadata["ARTIST"] != "Artist" {
+		t.Fatalf("artist = %q", metadata["ARTIST"])
+	}
+	if metadata["ALBUM"] != "Album" {
+		t.Fatalf("album = %q", metadata["ALBUM"])
+	}
+
+	for _, key := range []string{
+		"ALBUMARTIST",
+		"DATE",
+		"TRACKNUMBER",
+		"DISCNUMBER",
+		"ISRC",
+		"GENRE",
+		"ORGANIZATION",
+		"COPYRIGHT",
+		"LYRICS",
+		"UNSYNCEDLYRICS",
+	} {
+		if _, exists := metadata[key]; exists {
+			t.Fatalf("did not expect key %s in metadata: %#v", key, metadata)
+		}
+	}
+}
+
+func TestBuildReEnrichSearchQuerySkipsPlaceholderArtist(t *testing.T) {
+	req := reEnrichRequest{
+		TrackName:  "Sign of the Times",
+		ArtistName: "Unknown Artist",
+		AlbumName:  "Harry Styles",
+	}
+
+	query := buildReEnrichSearchQuery(req)
+	if query != "Sign of the Times" {
+		t.Fatalf("query = %q", query)
+	}
+
+	req = reEnrichRequest{
+		TrackName:  "Unknown Title",
+		ArtistName: "Unknown Artist",
+		AlbumName:  "Harry Styles",
+	}
+	query = buildReEnrichSearchQuery(req)
+	if query != "Harry Styles" {
+		t.Fatalf("fallback album query = %q", query)
+	}
+}
+
+func TestApplyReEnrichTrackMetadataCopiesComposerAndTotals(t *testing.T) {
+	req := reEnrichRequest{}
+
+	applyReEnrichTrackMetadata(&req, ExtTrackMetadata{
+		Name:        "Resolved Song",
+		Artists:     "Resolved Artist",
+		TrackNumber: 7,
+		TotalTracks: 12,
+		DiscNumber:  2,
+		TotalDiscs:  3,
+		Composer:    "Composer",
+	})
+
+	if req.TrackNumber != 7 || req.TotalTracks != 12 {
+		t.Fatalf("track metadata = %d/%d", req.TrackNumber, req.TotalTracks)
+	}
+	if req.DiscNumber != 2 || req.TotalDiscs != 3 {
+		t.Fatalf("disc metadata = %d/%d", req.DiscNumber, req.TotalDiscs)
+	}
+	if req.TrackName != "Resolved Song" || req.ArtistName != "Resolved Artist" {
+		t.Fatalf("basic tags = %q / %q", req.TrackName, req.ArtistName)
+	}
+	if req.Composer != "Composer" {
+		t.Fatalf("composer = %q", req.Composer)
+	}
+}
+
+func TestBuildReEnrichFFmpegMetadataFormatsTotalsAndComposer(t *testing.T) {
+	req := reEnrichRequest{
+		TrackNumber: 7,
+		TotalTracks: 12,
+		DiscNumber:  2,
+		TotalDiscs:  3,
+		Composer:    "Composer",
+	}
+
+	metadata := buildReEnrichFFmpegMetadata(&req, "")
+
+	if metadata["TRACKNUMBER"] != "7/12" {
+		t.Fatalf("TRACKNUMBER = %q", metadata["TRACKNUMBER"])
+	}
+	if metadata["DISCNUMBER"] != "2/3" {
+		t.Fatalf("DISCNUMBER = %q", metadata["DISCNUMBER"])
+	}
+	if metadata["COMPOSER"] != "Composer" {
+		t.Fatalf("COMPOSER = %q", metadata["COMPOSER"])
+	}
+}

go_backend/extension_manager.go

@@ -43,41 +43,101 @@ func compareVersions(v1, v2 string) int {
 	return 0
 }
 
-type LoadedExtension struct {
-	ID        string             `json:"id"`
-	Manifest  *ExtensionManifest `json:"manifest"`
-	VM        *goja.Runtime      `json:"-"`
-	VMMu      sync.Mutex         `json:"-"` // Mutex to prevent concurrent VM access
-	Enabled   bool               `json:"enabled"`
-	Error     string             `json:"error,omitempty"`
-	DataDir   string             `json:"data_dir"`
-	SourceDir string             `json:"source_dir"`
-	IconPath  string             `json:"icon_path"`
+type loadedExtension struct {
+	ID          string             `json:"id"`
+	Manifest    *ExtensionManifest `json:"manifest"`
+	VM          *goja.Runtime      `json:"-"`
+	VMMu        sync.Mutex         `json:"-"`
+	runtime     *extensionRuntime
+	initialized bool
+	Enabled     bool   `json:"enabled"`
+	Error       string `json:"error,omitempty"`
+	DataDir     string `json:"data_dir"`
+	SourceDir   string `json:"source_dir"`
+	IconPath    string `json:"icon_path"`
 }
 
-// ExtensionManager manages all loaded extensions
-type ExtensionManager struct {
+func getExtensionInitSettings(extensionID string) map[string]interface{} {
+	settings := GetExtensionSettingsStore().GetAll(extensionID)
+	if len(settings) == 0 {
+		return settings
+	}
+
+	filtered := make(map[string]interface{}, len(settings))
+	for key, value := range settings {
+		if strings.HasPrefix(key, "_") {
+			continue
+		}
+		filtered[key] = value
+	}
+	return filtered
+}
+
+func ensureRuntimeReadyLocked(ext *loadedExtension, applyStoredSettings bool) error {
+	if ext.VM == nil || ext.runtime == nil {
+		if err := initializeVMLocked(ext); err != nil {
+			ext.Error = err.Error()
+			ext.Enabled = false
+			return err
+		}
+	}
+
+	if applyStoredSettings && !ext.initialized {
+		settings := getExtensionInitSettings(ext.ID)
+		if len(settings) > 0 {
+			if err := initializeExtensionWithSettingsLocked(ext, settings); err != nil {
+				teardownVMLocked(ext)
+				ext.Error = err.Error()
+				ext.Enabled = false
+				return err
+			}
+		} else {
+			ext.initialized = true
+		}
+	}
+
+	ext.Error = ""
+	return nil
+}
+
+func (ext *loadedExtension) ensureRuntimeReady() error {
+	ext.VMMu.Lock()
+	defer ext.VMMu.Unlock()
+
+	return ensureRuntimeReadyLocked(ext, true)
+}
+
+func (ext *loadedExtension) lockReadyVM() (*goja.Runtime, error) {
+	ext.VMMu.Lock()
+	if err := ensureRuntimeReadyLocked(ext, true); err != nil {
+		ext.VMMu.Unlock()
+		return nil, err
+	}
+	return ext.VM, nil
+}
+
+type extensionManager struct {
 	mu            sync.RWMutex
-	extensions    map[string]*LoadedExtension
-	extensionsDir string // Base directory for extensions
-	dataDir       string // Base directory for extension data
+	extensions    map[string]*loadedExtension
+	extensionsDir string
+	dataDir       string
 }
 
 var (
-	globalExtManager     *ExtensionManager
+	globalExtManager     *extensionManager
 	globalExtManagerOnce sync.Once
 )
 
-func GetExtensionManager() *ExtensionManager {
+func getExtensionManager() *extensionManager {
 	globalExtManagerOnce.Do(func() {
-		globalExtManager = &ExtensionManager{
-			extensions: make(map[string]*LoadedExtension),
+		globalExtManager = &extensionManager{
+			extensions: make(map[string]*loadedExtension),
 		}
 	})
 	return globalExtManager
 }
 
-func (m *ExtensionManager) SetDirectories(extensionsDir, dataDir string) error {
+func (m *extensionManager) SetDirectories(extensionsDir, dataDir string) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -94,12 +154,11 @@ func (m *ExtensionManager) SetDirectories(extensionsDir, dataDir string) error {
 	return nil
 }
 
-func (m *ExtensionManager) LoadExtensionFromFile(filePath string) (*LoadedExtension, error) {
+func (m *extensionManager) LoadExtensionFromFile(filePath string) (*loadedExtension, error) {
 	if !strings.HasSuffix(strings.ToLower(filePath), ".spotiflac-ext") {
 		return nil, fmt.Errorf("Invalid file format. Please select a .spotiflac-ext file")
 	}
 
-	// Open the zip file
 	zipReader, err := zip.OpenReader(filePath)
 	if err != nil {
 		return nil, fmt.Errorf("Cannot open extension file. The file may be corrupted or not a valid extension package")
@@ -152,7 +211,6 @@ func (m *ExtensionManager) LoadExtensionFromFile(filePath string) (*LoadedExtens
 	if exists {
 		versionCompare := compareVersions(manifest.Version, existingVersion)
 		if versionCompare > 0 {
-			// This is an upgrade - call UpgradeExtension
 			return m.UpgradeExtension(filePath)
 		} else if versionCompare == 0 {
 			return nil, fmt.Errorf("Extension '%s' v%s is already installed", existingDisplayName, existingVersion)
@@ -214,7 +272,7 @@ func (m *ExtensionManager) LoadExtensionFromFile(filePath string) (*LoadedExtens
 		return nil, fmt.Errorf("failed to create extension data directory: %w", err)
 	}
 
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID:        manifest.Name,
 		Manifest:  manifest,
 		Enabled:   false, // New extensions start disabled
@@ -222,11 +280,10 @@ func (m *ExtensionManager) LoadExtensionFromFile(filePath string) (*LoadedExtens
 		SourceDir: extDir,
 	}
 
-	// Initialize Goja VM
-	if err := m.initializeVM(ext); err != nil {
+	if err := validateExtensionLoad(ext); err != nil {
 		ext.Error = err.Error()
 		ext.Enabled = false
-		GoLog("[Extension] Failed to initialize VM for %s: %v\n", manifest.Name, err)
+		GoLog("[Extension] Failed to validate extension %s: %v\n", manifest.Name, err)
 	}
 
 	m.extensions[manifest.Name] = ext
@@ -235,7 +292,10 @@ func (m *ExtensionManager) LoadExtensionFromFile(filePath string) (*LoadedExtens
 	return ext, nil
 }
 
-func (m *ExtensionManager) initializeVM(ext *LoadedExtension) error {
+func initializeVMLocked(ext *loadedExtension) error {
+	ext.VM = nil
+	ext.runtime = nil
+	ext.initialized = false
 	vm := goja.New()
 	ext.VM = vm
 
@@ -245,7 +305,8 @@ func (m *ExtensionManager) initializeVM(ext *LoadedExtension) error {
 		return fmt.Errorf("failed to read index.js: %w", err)
 	}
 
-	runtime := NewExtensionRuntime(ext)
+	runtime := newExtensionRuntime(ext)
+	ext.runtime = runtime
 	runtime.RegisterAPIs(vm)
 	runtime.RegisterGoBackendAPIs(vm)
 
@@ -269,13 +330,11 @@ func (m *ExtensionManager) initializeVM(ext *LoadedExtension) error {
 		return goja.Undefined()
 	})
 
-	// Run the extension code
 	_, err = vm.RunString(string(jsCode))
 	if err != nil {
 		return fmt.Errorf("failed to execute extension code: %w", err)
 	}
 
-	// Verify extension was registered
 	if registeredExtension == nil || goja.IsUndefined(registeredExtension) {
 		return fmt.Errorf("extension did not call registerExtension()")
 	}
@@ -283,8 +342,137 @@ func (m *ExtensionManager) initializeVM(ext *LoadedExtension) error {
 	return nil
 }
 
-// UnloadExtension unloads an extension by ID
-func (m *ExtensionManager) UnloadExtension(extensionID string) error {
+func (m *extensionManager) initializeVM(ext *loadedExtension) error {
+	ext.VMMu.Lock()
+	defer ext.VMMu.Unlock()
+	return initializeVMLocked(ext)
+}
+
+func initializeExtensionWithSettingsLocked(
+	ext *loadedExtension,
+	settings map[string]interface{},
+) error {
+	if ext.VM == nil {
+		return fmt.Errorf("Extension failed to load. Please reinstall the extension")
+	}
+
+	settingsJSON, err := json.Marshal(settings)
+	if err != nil {
+		return fmt.Errorf("Failed to save settings")
+	}
+
+	script := fmt.Sprintf(`
+		(function() {
+			var settings = %s;
+			if (typeof extension !== 'undefined' && typeof extension.initialize === 'function') {
+				try {
+					extension.initialize(settings);
+					return { success: true };
+				} catch (e) {
+					return { success: false, error: e.toString() };
+				}
+			}
+			return { success: true, message: 'no initialize function' };
+		})()
+	`, string(settingsJSON))
+
+	result, err := ext.VM.RunString(script)
+	if err != nil {
+		ext.Error = fmt.Sprintf("initialize failed: %v", err)
+		ext.Enabled = false
+		GoLog("[Extension] Initialize error for %s: %v\n", ext.ID, err)
+		return err
+	}
+
+	if result != nil && !goja.IsUndefined(result) {
+		exported := result.Export()
+		if resultMap, ok := exported.(map[string]interface{}); ok {
+			if success, ok := resultMap["success"].(bool); ok && !success {
+				errMsg := "unknown error"
+				if e, ok := resultMap["error"].(string); ok {
+					errMsg = e
+				}
+				ext.Error = errMsg
+				ext.Enabled = false
+				GoLog("[Extension] Initialize failed for %s: %s\n", ext.ID, errMsg)
+				return fmt.Errorf("initialize failed: %s", errMsg)
+			}
+		}
+	}
+
+	ext.initialized = true
+	GoLog("[Extension] Initialized %s\n", ext.ID)
+	return nil
+}
+
+func runCleanupLocked(ext *loadedExtension) error {
+	if ext.VM != nil {
+		script := `
+			(function() {
+				if (typeof extension !== 'undefined' && typeof extension.cleanup === 'function') {
+					try {
+						extension.cleanup();
+						return { success: true };
+					} catch (e) {
+						return { success: false, error: e.toString() };
+					}
+				}
+				return { success: true, message: 'no cleanup function' };
+			})()
+		`
+
+		result, err := ext.VM.RunString(script)
+		if err != nil {
+			return err
+		}
+
+		if result != nil && !goja.IsUndefined(result) {
+			exported := result.Export()
+			if resultMap, ok := exported.(map[string]interface{}); ok {
+				if success, ok := resultMap["success"].(bool); ok && !success {
+					errMsg := "unknown error"
+					if e, ok := resultMap["error"].(string); ok {
+						errMsg = e
+					}
+					return fmt.Errorf("cleanup failed: %s", errMsg)
+				}
+			}
+		}
+
+		if result != nil && !goja.IsUndefined(result) && !goja.IsNull(result) {
+			GoLog("[Extension] Cleanup called for %s\n", ext.ID)
+		}
+	}
+	return nil
+}
+
+func teardownVMLocked(ext *loadedExtension) {
+	if err := runCleanupLocked(ext); err != nil {
+		GoLog("[Extension] Error calling cleanup for %s: %v\n", ext.ID, err)
+	}
+	if ext.runtime != nil {
+		if err := ext.runtime.flushStorageNow(); err != nil {
+			GoLog("[Extension] Failed to flush storage for %s: %v\n", ext.ID, err)
+		}
+		ext.runtime.closeStorageFlusher()
+	}
+	ext.runtime = nil
+	ext.VM = nil
+	ext.initialized = false
+}
+
+func validateExtensionLoad(ext *loadedExtension) error {
+	ext.VMMu.Lock()
+	defer ext.VMMu.Unlock()
+
+	if err := initializeVMLocked(ext); err != nil {
+		return err
+	}
+	teardownVMLocked(ext)
+	return nil
+}
+
+func (m *extensionManager) UnloadExtension(extensionID string) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -293,26 +481,17 @@ func (m *ExtensionManager) UnloadExtension(extensionID string) error {
 		return fmt.Errorf("Extension not found")
 	}
 
-	// Call cleanup if VM is initialized
-	if ext.VM != nil {
-		// Try to call cleanup function
-		cleanup, err := ext.VM.RunString("typeof extension !== 'undefined' && typeof extension.cleanup === 'function' ? extension.cleanup() : null")
-		if err != nil {
-			GoLog("[Extension] Error calling cleanup for %s: %v\n", extensionID, err)
-		} else if cleanup != nil && !goja.IsUndefined(cleanup) && !goja.IsNull(cleanup) {
-			GoLog("[Extension] Cleanup called for %s\n", extensionID)
-		}
-	}
+	ext.VMMu.Lock()
+	teardownVMLocked(ext)
+	ext.VMMu.Unlock()
 
-	// Remove from registry
 	delete(m.extensions, extensionID)
 	GoLog("[Extension] Unloaded extension: %s\n", extensionID)
 
 	return nil
 }
 
-// Returns error if extension not found (gomobile compatible)
-func (m *ExtensionManager) GetExtension(extensionID string) (*LoadedExtension, error) {
+func (m *extensionManager) GetExtension(extensionID string) (*loadedExtension, error) {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
 
@@ -323,19 +502,18 @@ func (m *ExtensionManager) GetExtension(extensionID string) (*LoadedExtension, e
 	return ext, nil
 }
 
-// GetAllExtensions returns all loaded extensions
-func (m *ExtensionManager) GetAllExtensions() []*LoadedExtension {
+func (m *extensionManager) GetAllExtensions() []*loadedExtension {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
 
-	result := make([]*LoadedExtension, 0, len(m.extensions))
+	result := make([]*loadedExtension, 0, len(m.extensions))
 	for _, ext := range m.extensions {
 		result = append(result, ext)
 	}
 	return result
 }
 
-func (m *ExtensionManager) SetExtensionEnabled(extensionID string, enabled bool) error {
+func (m *extensionManager) SetExtensionEnabled(extensionID string, enabled bool) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -344,10 +522,23 @@ func (m *ExtensionManager) SetExtensionEnabled(extensionID string, enabled bool)
 		return fmt.Errorf("Extension not found")
 	}
 
-	ext.Enabled = enabled
+	if enabled {
+		ext.Enabled = true
+		if err := ext.ensureRuntimeReady(); err != nil {
+			store := GetExtensionSettingsStore()
+			ext.Enabled = false
+			_ = store.Set(extensionID, "_enabled", false)
+			return err
+		}
+	} else {
+		ext.Enabled = false
+		ext.Error = ""
+		ext.VMMu.Lock()
+		teardownVMLocked(ext)
+		ext.VMMu.Unlock()
+	}
 	GoLog("[Extension] %s %s\n", extensionID, map[bool]string{true: "enabled", false: "disabled"}[enabled])
 
-	// Persist enabled state to settings store
 	store := GetExtensionSettingsStore()
 	if err := store.Set(extensionID, "_enabled", enabled); err != nil {
 		GoLog("[Extension] Failed to persist enabled state for %s: %v\n", extensionID, err)
@@ -356,8 +547,7 @@ func (m *ExtensionManager) SetExtensionEnabled(extensionID string, enabled bool)
 	return nil
 }
 
-// LoadExtensionsFromDirectory scans a directory and loads all valid extensions
-func (m *ExtensionManager) LoadExtensionsFromDirectory(dirPath string) ([]string, []error) {
+func (m *extensionManager) LoadExtensionsFromDirectory(dirPath string) ([]string, []error) {
 	var loaded []string
 	var errors []error
 
@@ -395,7 +585,7 @@ func (m *ExtensionManager) LoadExtensionsFromDirectory(dirPath string) ([]string
 	return loaded, errors
 }
 
-func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedExtension, error) {
+func (m *extensionManager) loadExtensionFromDirectory(dirPath string) (*loadedExtension, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -405,7 +595,6 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 		return nil, fmt.Errorf("failed to read manifest.json: %w", err)
 	}
 
-	// Parse and validate manifest
 	manifest, err := ParseManifest(manifestData)
 	if err != nil {
 		return nil, fmt.Errorf("Invalid extension manifest: %w", err)
@@ -426,7 +615,7 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 		return nil, fmt.Errorf("failed to create extension data directory: %w", err)
 	}
 
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID:        manifest.Name,
 		Manifest:  manifest,
 		Enabled:   false, // Will be restored from settings store
@@ -434,7 +623,6 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 		SourceDir: dirPath,
 	}
 
-	// Restore enabled state from settings store
 	store := GetExtensionSettingsStore()
 	if enabledVal, err := store.Get(manifest.Name, "_enabled"); err == nil {
 		if enabled, ok := enabledVal.(bool); ok {
@@ -443,11 +631,10 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 		}
 	}
 
-	// Initialize Goja VM
-	if err := m.initializeVM(ext); err != nil {
+	if err := validateExtensionLoad(ext); err != nil {
 		ext.Error = err.Error()
 		ext.Enabled = false
-		GoLog("[Extension] Failed to initialize VM for %s: %v\n", manifest.Name, err)
+		GoLog("[Extension] Failed to validate extension %s: %v\n", manifest.Name, err)
 	}
 
 	m.extensions[manifest.Name] = ext
@@ -456,41 +643,31 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 	return ext, nil
 }
 
-// RemoveExtension completely removes an extension (unload + delete files)
-func (m *ExtensionManager) RemoveExtension(extensionID string) error {
+func (m *extensionManager) RemoveExtension(extensionID string) error {
 	ext, err := m.GetExtension(extensionID)
 	if err != nil {
 		return err
 	}
 
-	// Unload first
 	if err := m.UnloadExtension(extensionID); err != nil {
 		return err
 	}
 
-	// Remove source directory
 	if ext.SourceDir != "" {
 		if err := os.RemoveAll(ext.SourceDir); err != nil {
 			GoLog("[Extension] Warning: failed to remove source dir: %v\n", err)
 		}
 	}
 
-	// Optionally remove data directory (keep for now to preserve settings)
-	// if ext.DataDir != "" {
-	//     os.RemoveAll(ext.DataDir)
-	// }
-
 	return nil
 }
 
 // Only allows upgrades (new version > current version), not downgrades
-func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension, error) {
-	// Validate file extension
+func (m *extensionManager) UpgradeExtension(filePath string) (*loadedExtension, error) {
 	if !strings.HasSuffix(strings.ToLower(filePath), ".spotiflac-ext") {
 		return nil, fmt.Errorf("Invalid file format. Please select a .spotiflac-ext file")
 	}
 
-	// Open the zip file
 	zipReader, err := zip.OpenReader(filePath)
 	if err != nil {
 		return nil, fmt.Errorf("Cannot open extension file. The file may be corrupted or not a valid extension package")
@@ -538,7 +715,6 @@ func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension,
 		return nil, fmt.Errorf("Extension '%s' is not installed. Use install instead of upgrade.", newManifest.DisplayName)
 	}
 
-	// Compare versions - only allow upgrade, not downgrade
 	versionCompare := compareVersions(newManifest.Version, existing.Manifest.Version)
 	if versionCompare < 0 {
 		return nil, fmt.Errorf("Cannot downgrade extension. Current version: %s, New version: %s", existing.Manifest.Version, newManifest.Version)
@@ -549,16 +725,12 @@ func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension,
 
 	GoLog("[Extension] Upgrading %s from v%s to v%s\n", newManifest.DisplayName, existing.Manifest.Version, newManifest.Version)
 
-	// Save data directory path and enabled state (we want to preserve them)
 	extDataDir := existing.DataDir
 	extDir := existing.SourceDir
 	wasEnabled := existing.Enabled
 
-	// Cleanup and unload existing extension
-	m.CleanupExtension(existing.ID)
 	m.UnloadExtension(existing.ID)
 
-	// Remove old source files but keep data directory
 	if extDir != "" {
 		if err := os.RemoveAll(extDir); err != nil {
 			GoLog("[Extension] Warning: failed to remove old source dir: %v\n", err)
@@ -605,7 +777,7 @@ func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension,
 		}
 	}
 
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID:        newManifest.Name,
 		Manifest:  newManifest,
 		Enabled:   wasEnabled, // Preserve enabled state from before upgrade
@@ -613,11 +785,14 @@ func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension,
 		SourceDir: extDir,
 	}
 
-	// Initialize Goja VM
-	if err := m.initializeVM(ext); err != nil {
+	if wasEnabled {
+		if err := ext.ensureRuntimeReady(); err != nil {
+			GoLog("[Extension] Failed to initialize upgraded extension %s: %v\n", newManifest.Name, err)
+		}
+	} else if err := validateExtensionLoad(ext); err != nil {
 		ext.Error = err.Error()
 		ext.Enabled = false
-		GoLog("[Extension] Failed to initialize VM for %s: %v\n", newManifest.Name, err)
+		GoLog("[Extension] Failed to validate upgraded extension %s: %v\n", newManifest.Name, err)
 	}
 
 	m.mu.Lock()
@@ -637,16 +812,13 @@ type ExtensionUpgradeInfo struct {
 	IsInstalled    bool   `json:"is_installed"`
 }
 
-// checkExtensionUpgradeInternal checks if a package file is an upgrade for an existing extension
-// Internal function that returns struct
-func (m *ExtensionManager) checkExtensionUpgradeInternal(filePath string) (*ExtensionUpgradeInfo, error) {
-	// Validate file extension
+func (m *extensionManager) checkExtensionUpgradeInternal(filePath string) (*ExtensionUpgradeInfo, error) {
 	if !strings.HasSuffix(strings.ToLower(filePath), ".spotiflac-ext") {
-		return nil, fmt.Errorf("Invalid file format")
+		return nil, fmt.Errorf("Invalid file format. Please select a .spotiflac-ext file")
 	}
 
-	// Open the zip file
 	zipReader, err := zip.OpenReader(filePath)
+
 	if err != nil {
 		return nil, fmt.Errorf("Cannot open extension file")
 	}
@@ -689,7 +861,6 @@ func (m *ExtensionManager) checkExtensionUpgradeInternal(filePath string) (*Exte
 	}
 
 	if !exists {
-		// Not installed - this is a new install, not upgrade
 		info.CurrentVersion = ""
 		info.CanUpgrade = false
 	} else {
@@ -700,7 +871,7 @@ func (m *ExtensionManager) checkExtensionUpgradeInternal(filePath string) (*Exte
 	return info, nil
 }
 
-func (m *ExtensionManager) CheckExtensionUpgradeJSON(filePath string) (string, error) {
+func (m *extensionManager) CheckExtensionUpgradeJSON(filePath string) (string, error) {
 	info, err := m.checkExtensionUpgradeInternal(filePath)
 	if err != nil {
 		return "", err
@@ -714,8 +885,7 @@ func (m *ExtensionManager) CheckExtensionUpgradeJSON(filePath string) (string, e
 	return string(jsonBytes), nil
 }
 
-// GetInstalledExtensionsJSON returns all extensions as JSON for Flutter
-func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
+func (m *extensionManager) GetInstalledExtensionsJSON() (string, error) {
 	extensions := m.GetAllExtensions()
 
 	type ExtensionInfo struct {
@@ -736,7 +906,9 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 		Permissions            []string               `json:"permissions"`
 		HasMetadataProvider    bool                   `json:"has_metadata_provider"`
 		HasDownloadProvider    bool                   `json:"has_download_provider"`
+		HasLyricsProvider      bool                   `json:"has_lyrics_provider"`
 		SkipMetadataEnrichment bool                   `json:"skip_metadata_enrichment"`
+		SkipLyrics             bool                   `json:"skip_lyrics"`
 		SearchBehavior         *SearchBehaviorConfig  `json:"search_behavior,omitempty"`
 		TrackMatching          *TrackMatchingConfig   `json:"track_matching,omitempty"`
 		PostProcessing         *PostProcessingConfig  `json:"post_processing,omitempty"`
@@ -753,7 +925,6 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 			permissions = append(permissions, "storage:enabled")
 		}
 
-		// Determine status
 		status := "loaded"
 		if ext.Error != "" {
 			status = "error"
@@ -793,7 +964,9 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 			Permissions:            permissions,
 			HasMetadataProvider:    ext.Manifest.IsMetadataProvider(),
 			HasDownloadProvider:    ext.Manifest.IsDownloadProvider(),
+			HasLyricsProvider:      ext.Manifest.IsLyricsProvider(),
 			SkipMetadataEnrichment: ext.Manifest.SkipMetadataEnrichment,
+			SkipLyrics:             ext.Manifest.SkipLyrics,
 			SearchBehavior:         ext.Manifest.SearchBehavior,
 			TrackMatching:          ext.Manifest.TrackMatching,
 			PostProcessing:         ext.Manifest.PostProcessing,
@@ -809,9 +982,7 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 	return string(jsonBytes), nil
 }
 
-// ==================== Extension Lifecycle ====================
-
-func (m *ExtensionManager) InitializeExtension(extensionID string, settings map[string]interface{}) error {
+func (m *extensionManager) InitializeExtension(extensionID string, settings map[string]interface{}) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -820,59 +991,16 @@ func (m *ExtensionManager) InitializeExtension(extensionID string, settings map[
 		return fmt.Errorf("Extension not found")
 	}
 
-	if ext.VM == nil {
-		return fmt.Errorf("Extension failed to load. Please reinstall the extension")
-	}
+	ext.VMMu.Lock()
+	defer ext.VMMu.Unlock()
 
-	settingsJSON, err := json.Marshal(settings)
-	if err != nil {
-		return fmt.Errorf("Failed to save settings")
-	}
-
-	script := fmt.Sprintf(`
-		(function() {
-			var settings = %s;
-			if (typeof extension !== 'undefined' && typeof extension.initialize === 'function') {
-				try {
-					extension.initialize(settings);
-					return { success: true };
-				} catch (e) {
-					return { success: false, error: e.toString() };
-				}
-			}
-			return { success: true, message: 'no initialize function' };
-		})()
-	`, string(settingsJSON))
-
-	result, err := ext.VM.RunString(script)
-	if err != nil {
-		ext.Error = fmt.Sprintf("initialize failed: %v", err)
-		ext.Enabled = false
-		GoLog("[Extension] Initialize error for %s: %v\n", extensionID, err)
+	if err := ensureRuntimeReadyLocked(ext, false); err != nil {
 		return err
 	}
-
-	if result != nil && !goja.IsUndefined(result) {
-		exported := result.Export()
-		if resultMap, ok := exported.(map[string]interface{}); ok {
-			if success, ok := resultMap["success"].(bool); ok && !success {
-				errMsg := "unknown error"
-				if e, ok := resultMap["error"].(string); ok {
-					errMsg = e
-				}
-				ext.Error = errMsg
-				ext.Enabled = false
-				GoLog("[Extension] Initialize failed for %s: %s\n", extensionID, errMsg)
-				return fmt.Errorf("initialize failed: %s", errMsg)
-			}
-		}
-	}
-
-	GoLog("[Extension] Initialized %s\n", extensionID)
-	return nil
+	return initializeExtensionWithSettingsLocked(ext, settings)
 }
 
-func (m *ExtensionManager) CleanupExtension(extensionID string) error {
+func (m *extensionManager) CleanupExtension(extensionID string) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -884,47 +1012,17 @@ func (m *ExtensionManager) CleanupExtension(extensionID string) error {
 	if ext.VM == nil {
 		return nil
 	}
-
-	script := `
-		(function() {
-			if (typeof extension !== 'undefined' && typeof extension.cleanup === 'function') {
-				try {
-					extension.cleanup();
-					return { success: true };
-				} catch (e) {
-					return { success: false, error: e.toString() };
-				}
-			}
-			return { success: true, message: 'no cleanup function' };
-		})()
-	`
-
-	result, err := ext.VM.RunString(script)
-	if err != nil {
+	ext.VMMu.Lock()
+	defer ext.VMMu.Unlock()
+	if err := runCleanupLocked(ext); err != nil {
 		GoLog("[Extension] Cleanup error for %s: %v\n", extensionID, err)
 		return err
 	}
-
-	if result != nil && !goja.IsUndefined(result) {
-		exported := result.Export()
-		if resultMap, ok := exported.(map[string]interface{}); ok {
-			if success, ok := resultMap["success"].(bool); ok && !success {
-				errMsg := "unknown error"
-				if e, ok := resultMap["error"].(string); ok {
-					errMsg = e
-				}
-				GoLog("[Extension] Cleanup failed for %s: %s\n", extensionID, errMsg)
-				return fmt.Errorf("cleanup failed: %s", errMsg)
-			}
-		}
-	}
-
 	GoLog("[Extension] Cleaned up %s\n", extensionID)
 	return nil
 }
 
-// UnloadAllExtensions unloads all extensions gracefully
-func (m *ExtensionManager) UnloadAllExtensions() {
+func (m *extensionManager) UnloadAllExtensions() {
 	m.mu.Lock()
 	extensionIDs := make([]string, 0, len(m.extensions))
 	for id := range m.extensions {
@@ -933,15 +1031,13 @@ func (m *ExtensionManager) UnloadAllExtensions() {
 	m.mu.Unlock()
 
 	for _, id := range extensionIDs {
-		m.CleanupExtension(id)
 		m.UnloadExtension(id)
 	}
 
 	GoLog("[Extension] All extensions unloaded\n")
 }
 
-// The function is called as extension.<actionName>() and can return a result
-func (m *ExtensionManager) InvokeAction(extensionID string, actionName string) (map[string]interface{}, error) {
+func (m *extensionManager) InvokeAction(extensionID string, actionName string) (map[string]interface{}, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -950,15 +1046,15 @@ func (m *ExtensionManager) InvokeAction(extensionID string, actionName string) (
 		return nil, fmt.Errorf("extension not found: %s", extensionID)
 	}
 
-	if ext.VM == nil {
-		return nil, fmt.Errorf("extension VM not initialized")
-	}
-
 	if !ext.Enabled {
 		return nil, fmt.Errorf("extension is disabled")
 	}
+	vm, err := ext.lockReadyVM()
+	if err != nil {
+		return nil, err
+	}
+	defer ext.VMMu.Unlock()
 
-	// Call the action function on the extension object
 	script := fmt.Sprintf(`
 		(function() {
 			if (typeof extension !== 'undefined' && typeof extension.%s === 'function') {
@@ -977,7 +1073,7 @@ func (m *ExtensionManager) InvokeAction(extensionID string, actionName string) (
 		})()
 	`, actionName, actionName, actionName)
 
-	result, err := RunWithTimeoutAndRecover(ext.VM, script, DefaultJSTimeout)
+	result, err := RunWithTimeoutAndRecover(vm, script, DefaultJSTimeout)
 	if err != nil {
 		GoLog("[Extension] InvokeAction error for %s.%s: %v\n", extensionID, actionName, err)
 		return nil, fmt.Errorf("action failed: %v", err)

go_backend/extension_manifest.go

@@ -1,4 +1,3 @@
-// Package gobackend provides extension manifest parsing and validation
 package gobackend
 
 import (
@@ -7,15 +6,14 @@ import (
 	"strings"
 )
 
-// ExtensionType represents the type of extension
 type ExtensionType string
 
 const (
 	ExtensionTypeMetadataProvider ExtensionType = "metadata_provider"
 	ExtensionTypeDownloadProvider ExtensionType = "download_provider"
+	ExtensionTypeLyricsProvider   ExtensionType = "lyrics_provider"
 )
 
-// SettingType represents the type of a setting field
 type SettingType string
 
 const (
@@ -26,14 +24,12 @@ const (
 	SettingTypeButton SettingType = "button" // Action button that calls a JS function
 )
 
-// ExtensionPermissions defines what resources an extension can access
 type ExtensionPermissions struct {
-	Network []string `json:"network"` // List of allowed domains
-	Storage bool     `json:"storage"` // Whether extension can use storage API
-	File    bool     `json:"file"`    // Whether extension can use file API
+	Network []string `json:"network"`
+	Storage bool     `json:"storage"`
+	File    bool     `json:"file"`
 }
 
-// ExtensionSetting defines a configurable setting for an extension
 type ExtensionSetting struct {
 	Key         string      `json:"key"`
 	Type        SettingType `json:"type"`
@@ -42,19 +38,17 @@ type ExtensionSetting struct {
 	Required    bool        `json:"required,omitempty"`
 	Secret      bool        `json:"secret,omitempty"`
 	Default     interface{} `json:"default,omitempty"`
-	Options     []string    `json:"options,omitempty"` // For select type
-	Action      string      `json:"action,omitempty"`  // For button type: JS function name to call (e.g., "startLogin")
+	Options     []string    `json:"options,omitempty"`
+	Action      string      `json:"action,omitempty"`
 }
 
-// QualityOption represents a quality option for download providers
 type QualityOption struct {
-	ID          string                   `json:"id"`                 // Unique identifier (e.g., "mp3_320", "opus_128")
-	Label       string                   `json:"label"`              // Display name (e.g., "MP3 320kbps")
-	Description string                   `json:"description"`        // Optional description (e.g., "Best quality MP3")
-	Settings    []QualitySpecificSetting `json:"settings,omitempty"` // Quality-specific settings
+	ID          string                   `json:"id"`
+	Label       string                   `json:"label"`
+	Description string                   `json:"description"`
+	Settings    []QualitySpecificSetting `json:"settings,omitempty"`
 }
 
-// QualitySpecificSetting represents a setting that's specific to a quality option
 type QualitySpecificSetting struct {
 	Key         string      `json:"key"`
 	Type        SettingType `json:"type"`
@@ -63,49 +57,50 @@ type QualitySpecificSetting struct {
 	Required    bool        `json:"required,omitempty"`
 	Secret      bool        `json:"secret,omitempty"`
 	Default     interface{} `json:"default,omitempty"`
-	Options     []string    `json:"options,omitempty"` // For select type
+	Options     []string    `json:"options,omitempty"`
+}
+
+type SearchFilter struct {
+	ID    string `json:"id"`
+	Label string `json:"label,omitempty"`
+	Icon  string `json:"icon,omitempty"`
 }
 
-// SearchBehaviorConfig defines custom search behavior for an extension
 type SearchBehaviorConfig struct {
-	Enabled         bool   `json:"enabled"`                   // Whether extension provides custom search
-	Placeholder     string `json:"placeholder,omitempty"`     // Placeholder text for search box
-	Primary         bool   `json:"primary,omitempty"`         // If true, show as primary search tab
-	Icon            string `json:"icon,omitempty"`            // Icon for search tab
-	ThumbnailRatio  string `json:"thumbnailRatio,omitempty"`  // Thumbnail aspect ratio: "square" (1:1), "wide" (16:9), "portrait" (2:3)
-	ThumbnailWidth  int    `json:"thumbnailWidth,omitempty"`  // Custom thumbnail width in pixels
-	ThumbnailHeight int    `json:"thumbnailHeight,omitempty"` // Custom thumbnail height in pixels
+	Enabled         bool           `json:"enabled"`
+	Placeholder     string         `json:"placeholder,omitempty"`
+	Primary         bool           `json:"primary,omitempty"`
+	Icon            string         `json:"icon,omitempty"`
+	ThumbnailRatio  string         `json:"thumbnailRatio,omitempty"`
+	ThumbnailWidth  int            `json:"thumbnailWidth,omitempty"`
+	ThumbnailHeight int            `json:"thumbnailHeight,omitempty"`
+	Filters         []SearchFilter `json:"filters,omitempty"`
 }
 
-// URLHandlerConfig defines custom URL handling for an extension
 type URLHandlerConfig struct {
-	Enabled  bool     `json:"enabled"`            // Whether extension handles URLs
-	Patterns []string `json:"patterns,omitempty"` // URL patterns to match (e.g., "music.youtube.com", "soundcloud.com")
+	Enabled  bool     `json:"enabled"`
+	Patterns []string `json:"patterns,omitempty"`
 }
 
-// TrackMatchingConfig defines custom track matching behavior
 type TrackMatchingConfig struct {
-	CustomMatching    bool   `json:"customMatching"`              // Whether extension handles matching
-	Strategy          string `json:"strategy,omitempty"`          // "isrc", "name", "duration", "custom"
-	DurationTolerance int    `json:"durationTolerance,omitempty"` // Tolerance in seconds for duration matching
+	CustomMatching    bool   `json:"customMatching"`
+	Strategy          string `json:"strategy,omitempty"`
+	DurationTolerance int    `json:"durationTolerance,omitempty"`
 }
 
-// PostProcessingHook defines a post-processing hook
 type PostProcessingHook struct {
-	ID               string   `json:"id"`                         // Unique identifier
-	Name             string   `json:"name"`                       // Display name
-	Description      string   `json:"description,omitempty"`      // Description
-	DefaultEnabled   bool     `json:"defaultEnabled,omitempty"`   // Whether enabled by default
-	SupportedFormats []string `json:"supportedFormats,omitempty"` // Supported file formats (e.g., ["flac", "mp3"])
+	ID               string   `json:"id"`
+	Name             string   `json:"name"`
+	Description      string   `json:"description,omitempty"`
+	DefaultEnabled   bool     `json:"defaultEnabled,omitempty"`
+	SupportedFormats []string `json:"supportedFormats,omitempty"`
 }
 
-// PostProcessingConfig defines post-processing capabilities
 type PostProcessingConfig struct {
-	Enabled bool                 `json:"enabled"`         // Whether extension provides post-processing
-	Hooks   []PostProcessingHook `json:"hooks,omitempty"` // Available hooks
+	Enabled bool                 `json:"enabled"`
+	Hooks   []PostProcessingHook `json:"hooks,omitempty"`
 }
 
-// ExtensionManifest represents the manifest.json of an extension
 type ExtensionManifest struct {
 	Name                   string                 `json:"name"`
 	DisplayName            string                 `json:"displayName"`
@@ -113,22 +108,22 @@ type ExtensionManifest struct {
 	Author                 string                 `json:"author"`
 	Description            string                 `json:"description"`
 	Homepage               string                 `json:"homepage,omitempty"`
-	Icon                   string                 `json:"icon,omitempty"` // Icon filename (e.g., "icon.png")
+	Icon                   string                 `json:"icon,omitempty"`
 	Types                  []ExtensionType        `json:"type"`
 	Permissions            ExtensionPermissions   `json:"permissions"`
 	Settings               []ExtensionSetting     `json:"settings,omitempty"`
-	QualityOptions         []QualityOption        `json:"qualityOptions,omitempty"` // Custom quality options for download providers
+	QualityOptions         []QualityOption        `json:"qualityOptions,omitempty"`
 	MinAppVersion          string                 `json:"minAppVersion,omitempty"`
-	SkipMetadataEnrichment bool                   `json:"skipMetadataEnrichment,omitempty"` // If true, don't enrich metadata from Deezer/Spotify
-	SkipBuiltInFallback    bool                   `json:"skipBuiltInFallback,omitempty"`    // If true, don't fallback to built-in providers (tidal/qobuz/amazon)
-	SearchBehavior         *SearchBehaviorConfig  `json:"searchBehavior,omitempty"`         // Custom search behavior
-	URLHandler             *URLHandlerConfig      `json:"urlHandler,omitempty"`             // Custom URL handling
-	TrackMatching          *TrackMatchingConfig   `json:"trackMatching,omitempty"`          // Custom track matching
-	PostProcessing         *PostProcessingConfig  `json:"postProcessing,omitempty"`         // Post-processing hooks
-	Capabilities           map[string]interface{} `json:"capabilities,omitempty"`           // Extension capabilities (homeFeed, browseCategories, etc.)
+	SkipMetadataEnrichment bool                   `json:"skipMetadataEnrichment,omitempty"`
+	SkipLyrics             bool                   `json:"skipLyrics,omitempty"`
+	SkipBuiltInFallback    bool                   `json:"skipBuiltInFallback,omitempty"`
+	SearchBehavior         *SearchBehaviorConfig  `json:"searchBehavior,omitempty"`
+	URLHandler             *URLHandlerConfig      `json:"urlHandler,omitempty"`
+	TrackMatching          *TrackMatchingConfig   `json:"trackMatching,omitempty"`
+	PostProcessing         *PostProcessingConfig  `json:"postProcessing,omitempty"`
+	Capabilities           map[string]interface{} `json:"capabilities,omitempty"`
 }
 
-// ManifestValidationError represents a validation error in the manifest
 type ManifestValidationError struct {
 	Field   string
 	Message string
@@ -138,7 +133,6 @@ func (e *ManifestValidationError) Error() string {
 	return fmt.Sprintf("manifest validation error: %s - %s", e.Field, e.Message)
 }
 
-// ParseManifest parses and validates a manifest from JSON bytes
 func ParseManifest(data []byte) (*ExtensionManifest, error) {
 	var manifest ExtensionManifest
 	if err := json.Unmarshal(data, &manifest); err != nil {
@@ -174,15 +168,14 @@ func (m *ExtensionManifest) Validate() error {
 	}
 
 	for _, t := range m.Types {
-		if t != ExtensionTypeMetadataProvider && t != ExtensionTypeDownloadProvider {
+		if t != ExtensionTypeMetadataProvider && t != ExtensionTypeDownloadProvider && t != ExtensionTypeLyricsProvider {
 			return &ManifestValidationError{
 				Field:   "type",
-				Message: fmt.Sprintf("invalid extension type: %s (must be 'metadata_provider' or 'download_provider')", t),
+				Message: fmt.Sprintf("invalid extension type: %s (must be 'metadata_provider', 'download_provider', or 'lyrics_provider')", t),
 			}
 		}
 	}
 
-	// Validate settings if present
 	for i, setting := range m.Settings {
 		if strings.TrimSpace(setting.Key) == "" {
 			return &ManifestValidationError{
@@ -217,7 +210,6 @@ func (m *ExtensionManifest) Validate() error {
 	return nil
 }
 
-// HasType checks if the extension has a specific type
 func (m *ExtensionManifest) HasType(t ExtensionType) bool {
 	for _, et := range m.Types {
 		if et == t {
@@ -227,17 +219,18 @@ func (m *ExtensionManifest) HasType(t ExtensionType) bool {
 	return false
 }
 
-// IsMetadataProvider returns true if extension provides metadata
 func (m *ExtensionManifest) IsMetadataProvider() bool {
 	return m.HasType(ExtensionTypeMetadataProvider)
 }
 
-// IsDownloadProvider returns true if extension provides downloads
 func (m *ExtensionManifest) IsDownloadProvider() bool {
 	return m.HasType(ExtensionTypeDownloadProvider)
 }
 
-// IsDomainAllowed checks if a domain is in the allowed network permissions
+func (m *ExtensionManifest) IsLyricsProvider() bool {
+	return m.HasType(ExtensionTypeLyricsProvider)
+}
+
 func (m *ExtensionManifest) IsDomainAllowed(domain string) bool {
 	domain = strings.ToLower(strings.TrimSpace(domain))
 	for _, allowed := range m.Permissions.Network {
@@ -247,7 +240,7 @@ func (m *ExtensionManifest) IsDomainAllowed(domain string) bool {
 		}
 		// Support wildcard subdomains (e.g., *.example.com)
 		if strings.HasPrefix(allowed, "*.") {
-			suffix := allowed[1:] // Remove the *
+			suffix := allowed[1:]
 			if strings.HasSuffix(domain, suffix) {
 				return true
 			}
@@ -256,27 +249,22 @@ func (m *ExtensionManifest) IsDomainAllowed(domain string) bool {
 	return false
 }
 
-// HasCustomSearch returns true if extension provides custom search
 func (m *ExtensionManifest) HasCustomSearch() bool {
 	return m.SearchBehavior != nil && m.SearchBehavior.Enabled
 }
 
-// HasCustomMatching returns true if extension provides custom track matching
 func (m *ExtensionManifest) HasCustomMatching() bool {
 	return m.TrackMatching != nil && m.TrackMatching.CustomMatching
 }
 
-// HasPostProcessing returns true if extension provides post-processing
 func (m *ExtensionManifest) HasPostProcessing() bool {
 	return m.PostProcessing != nil && m.PostProcessing.Enabled
 }
 
-// HasURLHandler returns true if extension handles custom URLs
 func (m *ExtensionManifest) HasURLHandler() bool {
 	return m.URLHandler != nil && m.URLHandler.Enabled && len(m.URLHandler.Patterns) > 0
 }
 
-// MatchesURL checks if a URL matches any of the extension's URL patterns
 func (m *ExtensionManifest) MatchesURL(urlStr string) bool {
 	if !m.HasURLHandler() {
 		return false
@@ -285,7 +273,6 @@ func (m *ExtensionManifest) MatchesURL(urlStr string) bool {
 	urlStr = strings.ToLower(strings.TrimSpace(urlStr))
 	for _, pattern := range m.URLHandler.Patterns {
 		pattern = strings.ToLower(strings.TrimSpace(pattern))
-		// Check if URL contains the pattern (host match)
 		if strings.Contains(urlStr, pattern) {
 			return true
 		}
@@ -293,7 +280,6 @@ func (m *ExtensionManifest) MatchesURL(urlStr string) bool {
 	return false
 }
 
-// GetPostProcessingHooks returns all post-processing hooks
 func (m *ExtensionManifest) GetPostProcessingHooks() []PostProcessingHook {
 	if m.PostProcessing == nil {
 		return nil
@@ -301,7 +287,6 @@ func (m *ExtensionManifest) GetPostProcessingHooks() []PostProcessingHook {
 	return m.PostProcessing.Hooks
 }
 
-// ToJSON serializes the manifest to JSON
 func (m *ExtensionManifest) ToJSON() ([]byte, error) {
 	return json.Marshal(m)
 }

go_backend/extension_providers_test.go

@@ -0,0 +1,249 @@
+package gobackend
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestSetMetadataProviderPriorityAddsBuiltIns(t *testing.T) {
+	original := GetMetadataProviderPriority()
+	defer SetMetadataProviderPriority(original)
+
+	SetMetadataProviderPriority([]string{"tidal"})
+	got := GetMetadataProviderPriority()
+	want := []string{"tidal", "deezer", "qobuz"}
+	if len(got) != len(want) {
+		t.Fatalf("unexpected priority length: got %v want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("unexpected priority at %d: got %v want %v", i, got, want)
+		}
+	}
+}
+
+func TestSetExtensionFallbackProviderIDsSkipsBuiltInsAndDuplicates(t *testing.T) {
+	original := GetExtensionFallbackProviderIDs()
+	defer SetExtensionFallbackProviderIDs(original)
+
+	SetExtensionFallbackProviderIDs([]string{"ext-a", "tidal", "ext-a", " ext-b "})
+
+	got := GetExtensionFallbackProviderIDs()
+	want := []string{"ext-a", "ext-b"}
+	if len(got) != len(want) {
+		t.Fatalf("unexpected fallback provider length: got %v want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("unexpected fallback provider at %d: got %v want %v", i, got, want)
+		}
+	}
+}
+
+func TestIsExtensionFallbackAllowedDefaultsToAllExtensions(t *testing.T) {
+	original := GetExtensionFallbackProviderIDs()
+	defer SetExtensionFallbackProviderIDs(original)
+
+	SetExtensionFallbackProviderIDs(nil)
+
+	if !isExtensionFallbackAllowed("custom-ext") {
+		t.Fatal("expected custom extension to be allowed when no fallback allowlist is configured")
+	}
+	if !isExtensionFallbackAllowed("qobuz") {
+		t.Fatal("expected built-in provider to remain allowed")
+	}
+}
+
+func TestIsExtensionFallbackAllowedRespectsAllowlist(t *testing.T) {
+	original := GetExtensionFallbackProviderIDs()
+	defer SetExtensionFallbackProviderIDs(original)
+
+	SetExtensionFallbackProviderIDs([]string{"allowed-ext"})
+
+	if !isExtensionFallbackAllowed("allowed-ext") {
+		t.Fatal("expected explicitly allowed extension to be permitted")
+	}
+	if isExtensionFallbackAllowed("blocked-ext") {
+		t.Fatal("expected extension outside allowlist to be blocked")
+	}
+	if isExtensionFallbackAllowed("deezer") {
+		t.Fatal("expected retired Deezer downloader to respect extension fallback allowlist")
+	}
+}
+
+func TestSetProviderPriorityRemovesRetiredDeezerDownloader(t *testing.T) {
+	original := GetProviderPriority()
+	defer SetProviderPriority(original)
+
+	SetProviderPriority([]string{"deezer", "qobuz", "custom-ext"})
+
+	got := GetProviderPriority()
+	want := []string{"qobuz", "custom-ext", "tidal"}
+	if len(got) != len(want) {
+		t.Fatalf("unexpected priority length: got %v want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("unexpected priority at %d: got %v want %v", i, got, want)
+		}
+	}
+}
+
+func TestNormalizeDownloadDecryptionInfoPromotesLegacyKey(t *testing.T) {
+	normalized := normalizeDownloadDecryptionInfo(nil, " 001122 ")
+	if normalized == nil {
+		t.Fatal("expected legacy decryption key to produce normalized descriptor")
+	}
+	if normalized.Strategy != genericFFmpegMOVDecryptionStrategy {
+		t.Fatalf("strategy = %q", normalized.Strategy)
+	}
+	if normalized.Key != "001122" {
+		t.Fatalf("key = %q", normalized.Key)
+	}
+	if normalized.InputFormat != "mov" {
+		t.Fatalf("input format = %q", normalized.InputFormat)
+	}
+}
+
+func TestNormalizeDownloadDecryptionInfoCanonicalizesMovAliases(t *testing.T) {
+	normalized := normalizeDownloadDecryptionInfo(&DownloadDecryptionInfo{
+		Strategy:    "mp4_decryption_key",
+		Key:         "abcd",
+		InputFormat: "",
+	}, "")
+	if normalized == nil {
+		t.Fatal("expected descriptor to remain available")
+	}
+	if normalized.Strategy != genericFFmpegMOVDecryptionStrategy {
+		t.Fatalf("strategy = %q", normalized.Strategy)
+	}
+	if normalized.InputFormat != "mov" {
+		t.Fatalf("input format = %q", normalized.InputFormat)
+	}
+}
+
+func TestBuildOutputPathAddsExplicitOutputDirToAllowedDirs(t *testing.T) {
+	SetAllowedDownloadDirs(nil)
+
+	outputDir := t.TempDir()
+	outputPath := buildOutputPath(DownloadRequest{
+		TrackName:      "Song",
+		ArtistName:     "Artist",
+		OutputDir:      outputDir,
+		OutputExt:      ".flac",
+		FilenameFormat: "",
+	})
+
+	if !isPathInAllowedDirs(outputPath) {
+		t.Fatalf("expected output path %q to be allowed", outputPath)
+	}
+}
+
+func TestBuildOutputPathForExtensionAddsExplicitOutputPathDirToAllowedDirs(t *testing.T) {
+	SetAllowedDownloadDirs(nil)
+
+	outputDir := t.TempDir()
+	outputPath := filepath.Join(outputDir, "custom.flac")
+	ext := &loadedExtension{DataDir: t.TempDir()}
+
+	resolved := buildOutputPathForExtension(DownloadRequest{
+		OutputPath: outputPath,
+	}, ext)
+
+	if resolved != outputPath {
+		t.Fatalf("resolved output path = %q", resolved)
+	}
+	if !isPathInAllowedDirs(outputPath) {
+		t.Fatalf("expected output path %q to be allowed", outputPath)
+	}
+}
+
+func TestBuildOutputPathForExtensionUsesTempDirForFDOutput(t *testing.T) {
+	SetAllowedDownloadDirs(nil)
+
+	ext := &loadedExtension{DataDir: t.TempDir()}
+	resolved := buildOutputPathForExtension(DownloadRequest{
+		TrackName:  "Song",
+		ArtistName: "Artist",
+		OutputDir:  filepath.Join("Artist", "Album"),
+		OutputFD:   123,
+		OutputExt:  ".flac",
+	}, ext)
+
+	expectedBase := filepath.Join(ext.DataDir, "downloads")
+	if !isPathWithinBase(expectedBase, resolved) {
+		t.Fatalf("expected SAF extension output under %q, got %q", expectedBase, resolved)
+	}
+	if !isPathInAllowedDirs(resolved) {
+		t.Fatalf("expected resolved output path %q to be allowed", resolved)
+	}
+}
+
+func TestCanEmbedGenreLabelRequiresExistingAbsoluteLocalFile(t *testing.T) {
+	tempFile := filepath.Join(t.TempDir(), "track.flac")
+	if err := os.WriteFile(tempFile, []byte("fLaC"), 0644); err != nil {
+		t.Fatalf("failed to create temp file: %v", err)
+	}
+
+	if canEmbedGenreLabel("relative.flac") {
+		t.Fatal("expected relative path to be rejected")
+	}
+	if canEmbedGenreLabel("content://example") {
+		t.Fatal("expected content URI to be rejected")
+	}
+	if canEmbedGenreLabel(filepath.Join(t.TempDir(), "missing.flac")) {
+		t.Fatal("expected missing file to be rejected")
+	}
+	if !canEmbedGenreLabel(tempFile) {
+		t.Fatalf("expected existing absolute file %q to be accepted", tempFile)
+	}
+}
+
+func TestSearchTracksWithMetadataProvidersUsesPriorityAndDedupes(t *testing.T) {
+	originalPriority := GetMetadataProviderPriority()
+	originalSearch := searchBuiltInMetadataTracksFunc
+	defer func() {
+		SetMetadataProviderPriority(originalPriority)
+		searchBuiltInMetadataTracksFunc = originalSearch
+	}()
+
+	SetMetadataProviderPriority([]string{"qobuz", "tidal", "deezer"})
+
+	var calls []string
+	searchBuiltInMetadataTracksFunc = func(providerID, query string, limit int) ([]ExtTrackMetadata, error) {
+		calls = append(calls, providerID)
+		switch providerID {
+		case "qobuz":
+			return []ExtTrackMetadata{
+				{ProviderID: "qobuz", SpotifyID: "qobuz:1", ISRC: "AAA111", Name: "First"},
+			}, nil
+		case "tidal":
+			return []ExtTrackMetadata{
+				{ProviderID: "tidal", SpotifyID: "tidal:2", ISRC: "AAA111", Name: "Duplicate"},
+				{ProviderID: "tidal", SpotifyID: "tidal:3", ISRC: "BBB222", Name: "Second"},
+			}, nil
+		case "deezer":
+			return []ExtTrackMetadata{
+				{ProviderID: "deezer", SpotifyID: "deezer:4", ISRC: "CCC333", Name: "Third"},
+			}, nil
+		default:
+			return nil, nil
+		}
+	}
+
+	manager := getExtensionManager()
+	tracks, err := manager.SearchTracksWithMetadataProviders("query", 3, false)
+	if err != nil {
+		t.Fatalf("SearchTracksWithMetadataProviders returned error: %v", err)
+	}
+	if len(tracks) != 3 {
+		t.Fatalf("unexpected track count: got %d want 3", len(tracks))
+	}
+	if tracks[0].ProviderID != "qobuz" || tracks[1].ProviderID != "tidal" || tracks[2].ProviderID != "deezer" {
+		t.Fatalf("unexpected track provider order: %+v", tracks)
+	}
+	if len(calls) != 3 || calls[0] != "qobuz" || calls[1] != "tidal" || calls[2] != "deezer" {
+		t.Fatalf("unexpected provider call order: %v", calls)
+	}
+}

go_backend/extension_runtime.go

@@ -1,8 +1,11 @@
 package gobackend
 
 import (
+	"fmt"
+	"net"
 	"net/http"
 	"net/url"
+	"strings"
 	"sync"
 	"time"
 
@@ -23,9 +26,8 @@ type ExtensionAuthState struct {
 	RefreshToken    string
 	ExpiresAt       time.Time
 	IsAuthenticated bool
-	// PKCE support
-	PKCEVerifier  string
-	PKCEChallenge string
+	PKCEVerifier    string
+	PKCEChallenge   string
 }
 
 type PendingAuthRequest struct {
@@ -39,7 +41,6 @@ var (
 	pendingAuthRequestsMu sync.RWMutex
 )
 
-// GetPendingAuthRequest returns pending auth request for an extension (called from Flutter)
 func GetPendingAuthRequest(extensionID string) *PendingAuthRequest {
 	pendingAuthRequestsMu.RLock()
 	defer pendingAuthRequestsMu.RUnlock()
@@ -79,54 +80,123 @@ func SetExtensionTokens(extensionID string, accessToken, refreshToken string, ex
 	state.IsAuthenticated = accessToken != ""
 }
 
-type ExtensionRuntime struct {
-	extensionID string
-	manifest    *ExtensionManifest
-	settings    map[string]interface{}
-	httpClient  *http.Client
-	cookieJar   http.CookieJar
-	dataDir     string
-	vm          *goja.Runtime
+type extensionRuntime struct {
+	extensionID    string
+	manifest       *ExtensionManifest
+	settings       map[string]interface{}
+	httpClient     *http.Client
+	downloadClient *http.Client
+	cookieJar      http.CookieJar
+	dataDir        string
+	vm             *goja.Runtime
+
+	activeDownloadMu     sync.RWMutex
+	activeDownloadItemID string
+
+	storageMu      sync.RWMutex
+	storageCache   map[string]interface{}
+	storageLoaded  bool
+	storageDirty   bool
+	storageClosed  bool
+	storageTimer   *time.Timer
+	storageWriteMu sync.Mutex
+
+	credentialsMu     sync.RWMutex
+	credentialsCache  map[string]interface{}
+	credentialsLoaded bool
+	storageFlushDelay time.Duration
 }
 
-func NewExtensionRuntime(ext *LoadedExtension) *ExtensionRuntime {
+type privateIPCacheEntry struct {
+	isPrivate bool
+	expiresAt time.Time
+}
+
+const (
+	privateIPCacheTTL      = 5 * time.Minute
+	privateIPErrorCacheTTL = 30 * time.Second
+	maxPrivateIPCacheSize  = 1024
+)
+
+var (
+	privateIPCache   = make(map[string]privateIPCacheEntry)
+	privateIPCacheMu sync.RWMutex
+)
+
+func newExtensionRuntime(ext *loadedExtension) *extensionRuntime {
 	jar, _ := newSimpleCookieJar()
 
-	runtime := &ExtensionRuntime{
-		extensionID: ext.ID,
-		manifest:    ext.Manifest,
-		settings:    make(map[string]interface{}),
-		cookieJar:   jar,
-		dataDir:     ext.DataDir,
-		vm:          ext.VM,
+	runtime := &extensionRuntime{
+		extensionID:       ext.ID,
+		manifest:          ext.Manifest,
+		settings:          make(map[string]interface{}),
+		cookieJar:         jar,
+		dataDir:           ext.DataDir,
+		vm:                ext.VM,
+		storageFlushDelay: defaultStorageFlushDelay,
 	}
 
-	client := &http.Client{
-		Timeout: 30 * time.Second,
-		Jar:     jar,
-		CheckRedirect: func(req *http.Request, via []*http.Request) error {
-			// Validate redirect target domain against allowed domains
-			domain := req.URL.Hostname()
-			if !ext.Manifest.IsDomainAllowed(domain) {
-				GoLog("[Extension:%s] Redirect blocked: domain '%s' not in allowed list\n", ext.ID, domain)
-				return &RedirectBlockedError{Domain: domain}
-			}
-			if isPrivateIP(domain) {
-				GoLog("[Extension:%s] Redirect blocked: private IP '%s'\n", ext.ID, domain)
-				return &RedirectBlockedError{Domain: domain, IsPrivate: true}
-			}
-			// Default redirect limit (10)
-			if len(via) >= 10 {
-				return http.ErrUseLastResponse
-			}
-			return nil
-		},
-	}
-	runtime.httpClient = client
+	runtime.httpClient = newExtensionHTTPClient(ext, jar, 30*time.Second)
+	runtime.downloadClient = newExtensionHTTPClient(ext, jar, DownloadTimeout)
 
 	return runtime
 }
 
+func (r *extensionRuntime) setActiveDownloadItemID(itemID string) {
+	r.activeDownloadMu.Lock()
+	defer r.activeDownloadMu.Unlock()
+	r.activeDownloadItemID = strings.TrimSpace(itemID)
+}
+
+func (r *extensionRuntime) clearActiveDownloadItemID() {
+	r.activeDownloadMu.Lock()
+	defer r.activeDownloadMu.Unlock()
+	r.activeDownloadItemID = ""
+}
+
+func (r *extensionRuntime) getActiveDownloadItemID() string {
+	r.activeDownloadMu.RLock()
+	defer r.activeDownloadMu.RUnlock()
+	return r.activeDownloadItemID
+}
+
+func newExtensionHTTPClient(ext *loadedExtension, jar http.CookieJar, timeout time.Duration) *http.Client {
+	// Extension sandbox enforces HTTPS-only domains. Do not apply global
+	// allow_http scheme downgrade here, because some extension APIs (e.g.
+	// spotify-web) will redirect http -> https and can end up in 301 loops.
+	// We still reuse sharedTransport so insecure TLS compatibility mode remains effective.
+	client := &http.Client{
+		Transport: sharedTransport,
+		Timeout:   timeout,
+		Jar:       jar,
+	}
+	client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
+		if req.URL.Scheme != "https" {
+			GoLog("[Extension:%s] Redirect blocked: non-https scheme '%s'\n", ext.ID, req.URL.Scheme)
+			return fmt.Errorf("redirect blocked: only https is allowed")
+		}
+
+		domain := req.URL.Hostname()
+		if domain == "" {
+			GoLog("[Extension:%s] Redirect blocked: missing hostname\n", ext.ID)
+			return fmt.Errorf("redirect blocked: hostname is required")
+		}
+		if !ext.Manifest.IsDomainAllowed(domain) {
+			GoLog("[Extension:%s] Redirect blocked: domain '%s' not in allowed list\n", ext.ID, domain)
+			return &RedirectBlockedError{Domain: domain}
+		}
+		if isPrivateIP(domain) {
+			GoLog("[Extension:%s] Redirect blocked: private IP '%s'\n", ext.ID, domain)
+			return &RedirectBlockedError{Domain: domain, IsPrivate: true}
+		}
+		if len(via) >= 10 {
+			return http.ErrUseLastResponse
+		}
+		return nil
+	}
+	return client
+}
+
 type RedirectBlockedError struct {
 	Domain    string
 	IsPrivate bool
@@ -139,37 +209,99 @@ func (e *RedirectBlockedError) Error() string {
 	return "redirect blocked: domain '" + e.Domain + "' not in allowed list"
 }
 
-// isPrivateIP checks if a hostname resolves to a private/local IP address
 func isPrivateIP(host string) bool {
-	// Block common private network patterns
-	// This is a simple check - for production, consider DNS resolution
-	privatePatterns := []string{
-		"localhost",
-		"127.",
-		"10.",
-		"172.16.", "172.17.", "172.18.", "172.19.",
-		"172.20.", "172.21.", "172.22.", "172.23.",
-		"172.24.", "172.25.", "172.26.", "172.27.",
-		"172.28.", "172.29.", "172.30.", "172.31.",
-		"192.168.",
-		"169.254.",
-		"::1",
-		"fc00:",
-		"fe80:",
+	hostLower := strings.ToLower(strings.TrimSpace(host))
+	if hostLower == "" {
+		return false
 	}
 
-	hostLower := host
-	for _, pattern := range privatePatterns {
-		if hostLower == pattern || len(hostLower) > len(pattern) && hostLower[:len(pattern)] == pattern {
-			return true
-		}
-	}
-
-	// Also block .local domains
-	if len(host) > 6 && host[len(host)-6:] == ".local" {
+	if hostLower == "localhost" || strings.HasSuffix(hostLower, ".local") {
 		return true
 	}
 
+	if ip := net.ParseIP(hostLower); ip != nil {
+		return isPrivateIPAddr(ip)
+	}
+
+	if cached, ok := getPrivateIPCache(hostLower); ok {
+		return cached
+	}
+
+	ips, err := net.LookupIP(hostLower)
+	if err != nil {
+		setPrivateIPCache(hostLower, false, privateIPErrorCacheTTL)
+		return false
+	}
+
+	isPrivate := false
+	for _, ip := range ips {
+		if isPrivateIPAddr(ip) {
+			isPrivate = true
+			break
+		}
+	}
+
+	setPrivateIPCache(hostLower, isPrivate, privateIPCacheTTL)
+	return isPrivate
+}
+
+func getPrivateIPCache(host string) (bool, bool) {
+	now := time.Now()
+
+	privateIPCacheMu.RLock()
+	entry, exists := privateIPCache[host]
+	privateIPCacheMu.RUnlock()
+	if !exists {
+		return false, false
+	}
+
+	if now.Before(entry.expiresAt) {
+		return entry.isPrivate, true
+	}
+
+	privateIPCacheMu.Lock()
+	delete(privateIPCache, host)
+	privateIPCacheMu.Unlock()
+	return false, false
+}
+
+func setPrivateIPCache(host string, isPrivate bool, ttl time.Duration) {
+	expiresAt := time.Now().Add(ttl)
+
+	privateIPCacheMu.Lock()
+	if len(privateIPCache) >= maxPrivateIPCacheSize {
+		now := time.Now()
+		for key, entry := range privateIPCache {
+			if now.After(entry.expiresAt) {
+				delete(privateIPCache, key)
+			}
+		}
+		if len(privateIPCache) >= maxPrivateIPCacheSize {
+			privateIPCache = make(map[string]privateIPCacheEntry)
+		}
+	}
+	privateIPCache[host] = privateIPCacheEntry{
+		isPrivate: isPrivate,
+		expiresAt: expiresAt,
+	}
+	privateIPCacheMu.Unlock()
+}
+
+func isPrivateIPAddr(ip net.IP) bool {
+	if ip == nil {
+		return false
+	}
+	if ip.IsLoopback() ||
+		ip.IsPrivate() ||
+		ip.IsLinkLocalUnicast() ||
+		ip.IsLinkLocalMulticast() ||
+		ip.IsMulticast() ||
+		ip.IsUnspecified() {
+		return true
+	}
+	if !ip.IsGlobalUnicast() {
+		return true
+	}
 	return false
 }
 
@@ -197,22 +329,20 @@ func (j *simpleCookieJar) Cookies(u *url.URL) []*http.Cookie {
 	return j.cookies[u.Host]
 }
 
-func (r *ExtensionRuntime) SetSettings(settings map[string]interface{}) {
+func (r *extensionRuntime) SetSettings(settings map[string]interface{}) {
 	r.settings = settings
 }
 
-// RegisterAPIs registers all sandboxed APIs to the Goja VM
-func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
+func (r *extensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	r.vm = vm
 
-	// HTTP client (sandboxed to allowed domains)
 	httpObj := vm.NewObject()
 	httpObj.Set("get", r.httpGet)
 	httpObj.Set("post", r.httpPost)
 	httpObj.Set("put", r.httpPut)
 	httpObj.Set("delete", r.httpDelete)
 	httpObj.Set("patch", r.httpPatch)
-	httpObj.Set("request", r.httpRequest) // Generic HTTP request (GET, POST, PUT, DELETE, etc.)
+	httpObj.Set("request", r.httpRequest)
 	httpObj.Set("clearCookies", r.httpClearCookies)
 	vm.Set("http", httpObj)
 
@@ -222,7 +352,6 @@ func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	storageObj.Set("remove", r.storageRemove)
 	vm.Set("storage", storageObj)
 
-	// Secure Credentials API (encrypted storage for sensitive data)
 	credentialsObj := vm.NewObject()
 	credentialsObj.Set("store", r.credentialsStore)
 	credentialsObj.Set("get", r.credentialsGet)
@@ -237,20 +366,20 @@ func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	authObj.Set("clearAuth", r.authClear)
 	authObj.Set("isAuthenticated", r.authIsAuthenticated)
 	authObj.Set("getTokens", r.authGetTokens)
-	// PKCE support
 	authObj.Set("generatePKCE", r.authGeneratePKCE)
 	authObj.Set("getPKCE", r.authGetPKCE)
 	authObj.Set("startOAuthWithPKCE", r.authStartOAuthWithPKCE)
 	authObj.Set("exchangeCodeWithPKCE", r.authExchangeCodeWithPKCE)
 	vm.Set("auth", authObj)
 
-	// File operations (sandboxed)
 	fileObj := vm.NewObject()
 	fileObj.Set("download", r.fileDownload)
 	fileObj.Set("exists", r.fileExists)
 	fileObj.Set("delete", r.fileDelete)
 	fileObj.Set("read", r.fileRead)
+	fileObj.Set("readBytes", r.fileReadBytes)
 	fileObj.Set("write", r.fileWrite)
+	fileObj.Set("writeBytes", r.fileWriteBytes)
 	fileObj.Set("copy", r.fileCopy)
 	fileObj.Set("move", r.fileMove)
 	fileObj.Set("getSize", r.fileGetSize)
@@ -262,7 +391,6 @@ func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	ffmpegObj.Set("convert", r.ffmpegConvert)
 	vm.Set("ffmpeg", ffmpegObj)
 
-	// Track matching API
 	matchingObj := vm.NewObject()
 	matchingObj.Set("compareStrings", r.matchingCompareStrings)
 	matchingObj.Set("compareDuration", r.matchingCompareDuration)
@@ -279,14 +407,14 @@ func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	utilsObj.Set("hmacSHA1", r.hmacSHA1)
 	utilsObj.Set("parseJSON", r.parseJSON)
 	utilsObj.Set("stringifyJSON", r.stringifyJSON)
-	// Crypto utilities for developers
 	utilsObj.Set("encrypt", r.cryptoEncrypt)
 	utilsObj.Set("decrypt", r.cryptoDecrypt)
+	utilsObj.Set("encryptBlockCipher", r.encryptBlockCipher)
+	utilsObj.Set("decryptBlockCipher", r.decryptBlockCipher)
 	utilsObj.Set("generateKey", r.cryptoGenerateKey)
 	utilsObj.Set("randomUserAgent", r.randomUserAgent)
 	vm.Set("utils", utilsObj)
 
-	// Log object (already set in extension_manager.go, but we can enhance it)
 	logObj := vm.NewObject()
 	logObj.Set("debug", r.logDebug)
 	logObj.Set("info", r.logInfo)
@@ -298,10 +426,6 @@ func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	gobackendObj.Set("sanitizeFilename", r.sanitizeFilenameWrapper)
 	vm.Set("gobackend", gobackendObj)
 
-	// ==================== Browser-like Polyfills ====================
-	// These make porting browser/Node.js libraries easier
-
-	// Global fetch() - Promise-style HTTP API (browser-compatible)
 	vm.Set("fetch", r.fetchPolyfill)
 
 	vm.Set("atob", r.atobPolyfill)

go_backend/extension_runtime_auth.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Auth API and PKCE support for extension runtime
 package gobackend
 
 import (
@@ -16,9 +15,44 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== Auth API (OAuth Support) ====================
+func validateExtensionAuthURL(urlStr string) error {
+	parsed, err := url.Parse(urlStr)
+	if err != nil {
+		return fmt.Errorf("invalid auth URL: %w", err)
+	}
 
-func (r *ExtensionRuntime) authOpenUrl(call goja.FunctionCall) goja.Value {
+	if parsed.Scheme != "https" {
+		return fmt.Errorf("invalid auth URL: only https is allowed")
+	}
+
+	host := parsed.Hostname()
+	if host == "" {
+		return fmt.Errorf("invalid auth URL: hostname is required")
+	}
+
+	if parsed.User != nil {
+		return fmt.Errorf("invalid auth URL: embedded credentials are not allowed")
+	}
+
+	if isPrivateIP(host) {
+		return fmt.Errorf("invalid auth URL: private/local network is not allowed")
+	}
+
+	return nil
+}
+
+func summarizeURLForLog(urlStr string) string {
+	parsed, err := url.Parse(urlStr)
+	if err != nil {
+		return urlStr
+	}
+	if parsed.Host == "" {
+		return parsed.Scheme + "://"
+	}
+	return fmt.Sprintf("%s://%s%s", parsed.Scheme, parsed.Host, parsed.Path)
+}
+
+func (r *extensionRuntime) authOpenUrl(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -32,6 +66,13 @@ func (r *ExtensionRuntime) authOpenUrl(call goja.FunctionCall) goja.Value {
 		callbackURL = call.Arguments[1].String()
 	}
 
+	if err := validateExtensionAuthURL(authURL); err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
 	pendingAuthRequestsMu.Lock()
 	pendingAuthRequests[r.extensionID] = &PendingAuthRequest{
 		ExtensionID: r.extensionID,
@@ -50,7 +91,7 @@ func (r *ExtensionRuntime) authOpenUrl(call goja.FunctionCall) goja.Value {
 	state.AuthCode = ""
 	extensionAuthStateMu.Unlock()
 
-	GoLog("[Extension:%s] Auth URL requested: %s\n", r.extensionID, authURL)
+	GoLog("[Extension:%s] Auth URL requested: %s\n", r.extensionID, summarizeURLForLog(authURL))
 
 	return r.vm.ToValue(map[string]interface{}{
 		"success": true,
@@ -58,7 +99,7 @@ func (r *ExtensionRuntime) authOpenUrl(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) authGetCode(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authGetCode(call goja.FunctionCall) goja.Value {
 	extensionAuthStateMu.RLock()
 	defer extensionAuthStateMu.RUnlock()
 
@@ -70,13 +111,11 @@ func (r *ExtensionRuntime) authGetCode(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(state.AuthCode)
 }
 
-// authSetCode sets auth code and tokens (can be called by extension after token exchange)
-func (r *ExtensionRuntime) authSetCode(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authSetCode(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
 	}
 
-	// Can accept either just auth code or an object with tokens
 	arg := call.Arguments[0].Export()
 
 	extensionAuthStateMu.Lock()
@@ -110,7 +149,7 @@ func (r *ExtensionRuntime) authSetCode(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(true)
 }
 
-func (r *ExtensionRuntime) authClear(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authClear(call goja.FunctionCall) goja.Value {
 	extensionAuthStateMu.Lock()
 	delete(extensionAuthState, r.extensionID)
 	extensionAuthStateMu.Unlock()
@@ -123,8 +162,7 @@ func (r *ExtensionRuntime) authClear(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(true)
 }
 
-// authIsAuthenticated checks if extension has valid auth
-func (r *ExtensionRuntime) authIsAuthenticated(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authIsAuthenticated(call goja.FunctionCall) goja.Value {
 	extensionAuthStateMu.RLock()
 	defer extensionAuthStateMu.RUnlock()
 
@@ -140,7 +178,7 @@ func (r *ExtensionRuntime) authIsAuthenticated(call goja.FunctionCall) goja.Valu
 	return r.vm.ToValue(state.IsAuthenticated)
 }
 
-func (r *ExtensionRuntime) authGetTokens(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authGetTokens(call goja.FunctionCall) goja.Value {
 	extensionAuthStateMu.RLock()
 	defer extensionAuthStateMu.RUnlock()
 
@@ -163,10 +201,6 @@ func (r *ExtensionRuntime) authGetTokens(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(result)
 }
 
-// ==================== PKCE Support ====================
-
-// generatePKCEVerifier generates a cryptographically random code verifier
-// Length should be between 43-128 characters (RFC 7636)
 func generatePKCEVerifier(length int) (string, error) {
 	if length < 43 {
 		length = 43
@@ -191,12 +225,10 @@ func generatePKCEVerifier(length int) (string, error) {
 
 func generatePKCEChallenge(verifier string) string {
 	hash := sha256.Sum256([]byte(verifier))
-	// Base64url encode without padding (RFC 7636)
 	return base64.RawURLEncoding.EncodeToString(hash[:])
 }
 
-func (r *ExtensionRuntime) authGeneratePKCE(call goja.FunctionCall) goja.Value {
-	// Default length is 64 characters
+func (r *extensionRuntime) authGeneratePKCE(call goja.FunctionCall) goja.Value {
 	length := 64
 	if len(call.Arguments) > 0 && !goja.IsUndefined(call.Arguments[0]) {
 		if l, ok := call.Arguments[0].Export().(float64); ok && l >= 43 && l <= 128 {
@@ -233,7 +265,7 @@ func (r *ExtensionRuntime) authGeneratePKCE(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) authGetPKCE(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authGetPKCE(call goja.FunctionCall) goja.Value {
 	extensionAuthStateMu.RLock()
 	defer extensionAuthStateMu.RUnlock()
 
@@ -249,10 +281,7 @@ func (r *ExtensionRuntime) authGetPKCE(call goja.FunctionCall) goja.Value {
 	})
 }
 
-// authStartOAuthWithPKCE is a high-level helper that generates PKCE and opens OAuth URL
-// config: { authUrl, clientId, redirectUri, scope, extraParams }
-// Returns: { success, authUrl, pkce: { verifier, challenge } }
-func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -269,7 +298,6 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 		})
 	}
 
-	// Required fields
 	authURL, _ := config["authUrl"].(string)
 	clientID, _ := config["clientId"].(string)
 	redirectURI, _ := config["redirectUri"].(string)
@@ -280,12 +308,16 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 			"error":   "authUrl, clientId, and redirectUri are required",
 		})
 	}
+	if err := validateExtensionAuthURL(authURL); err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
 
-	// Optional fields
 	scope, _ := config["scope"].(string)
 	extraParams, _ := config["extraParams"].(map[string]interface{})
 
-	// Generate PKCE
 	verifier, err := generatePKCEVerifier(64)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -295,7 +327,6 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 	}
 	challenge := generatePKCEChallenge(verifier)
 
-	// Store PKCE in auth state
 	extensionAuthStateMu.Lock()
 	state, exists := extensionAuthState[r.extensionID]
 	if !exists {
@@ -304,10 +335,9 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 	}
 	state.PKCEVerifier = verifier
 	state.PKCEChallenge = challenge
-	state.AuthCode = "" // Clear any previous auth code
+	state.AuthCode = ""
 	extensionAuthStateMu.Unlock()
 
-	// Build OAuth URL with PKCE parameters
 	parsedURL, err := url.Parse(authURL)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -327,7 +357,6 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 		query.Set("scope", scope)
 	}
 
-	// Add extra params
 	for k, v := range extraParams {
 		query.Set(k, fmt.Sprintf("%v", v))
 	}
@@ -335,7 +364,6 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 	parsedURL.RawQuery = query.Encode()
 	fullAuthURL := parsedURL.String()
 
-	// Store pending auth request for Flutter
 	pendingAuthRequestsMu.Lock()
 	pendingAuthRequests[r.extensionID] = &PendingAuthRequest{
 		ExtensionID: r.extensionID,
@@ -344,7 +372,7 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 	}
 	pendingAuthRequestsMu.Unlock()
 
-	GoLog("[Extension:%s] PKCE OAuth started: %s\n", r.extensionID, fullAuthURL)
+	GoLog("[Extension:%s] PKCE OAuth started: %s\n", r.extensionID, summarizeURLForLog(fullAuthURL))
 
 	return r.vm.ToValue(map[string]interface{}{
 		"success": true,
@@ -357,10 +385,7 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 	})
 }
 
-// authExchangeCodeWithPKCE exchanges auth code for tokens using PKCE
-// config: { tokenUrl, clientId, redirectUri, code, extraParams }
-// Uses the stored PKCE verifier automatically
-func (r *ExtensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -377,7 +402,6 @@ func (r *ExtensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja
 		})
 	}
 
-	// Required fields
 	tokenURL, _ := config["tokenUrl"].(string)
 	clientID, _ := config["clientId"].(string)
 	redirectURI, _ := config["redirectUri"].(string)
@@ -454,13 +478,17 @@ func (r *ExtensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja
 			"error":   err.Error(),
 		})
 	}
+	bodyPreview := sanitizeSensitiveLogText(string(body))
+	if len(bodyPreview) > 1000 {
+		bodyPreview = bodyPreview[:1000] + "...[truncated]"
+	}
 
 	var tokenResp map[string]interface{}
 	if err := json.Unmarshal(body, &tokenResp); err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
 			"error":   fmt.Sprintf("failed to parse token response: %v", err),
-			"body":    string(body),
+			"body":    bodyPreview,
 		})
 	}
 
@@ -481,7 +509,7 @@ func (r *ExtensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
 			"error":   "no access_token in response",
-			"body":    string(body),
+			"body":    bodyPreview,
 		})
 	}
 

go_backend/extension_runtime_binary.go

@@ -0,0 +1,359 @@
+package gobackend
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"encoding/base64"
+	"encoding/hex"
+	"fmt"
+	"strings"
+
+	"github.com/dop251/goja"
+	"golang.org/x/crypto/blowfish"
+)
+
+type runtimeBlockCipherOptions struct {
+	Algorithm      string
+	Mode           string
+	Key            []byte
+	IV             []byte
+	InputEncoding  string
+	OutputEncoding string
+	Padding        string
+}
+
+func parseRuntimeOptionsArgument(call goja.FunctionCall, index int) map[string]interface{} {
+	if len(call.Arguments) <= index {
+		return nil
+	}
+
+	value := call.Arguments[index]
+	if goja.IsUndefined(value) || goja.IsNull(value) {
+		return nil
+	}
+
+	exported := value.Export()
+	if options, ok := exported.(map[string]interface{}); ok {
+		return options
+	}
+	return nil
+}
+
+func runtimeOptionString(options map[string]interface{}, key, defaultValue string) string {
+	if options == nil {
+		return defaultValue
+	}
+	raw, ok := options[key]
+	if !ok || raw == nil {
+		return defaultValue
+	}
+	switch value := raw.(type) {
+	case string:
+		if trimmed := strings.TrimSpace(value); trimmed != "" {
+			return trimmed
+		}
+	case []byte:
+		if len(value) > 0 {
+			return string(value)
+		}
+	}
+	return defaultValue
+}
+
+func runtimeOptionBool(options map[string]interface{}, key string, defaultValue bool) bool {
+	if options == nil {
+		return defaultValue
+	}
+	raw, ok := options[key]
+	if !ok || raw == nil {
+		return defaultValue
+	}
+	switch value := raw.(type) {
+	case bool:
+		return value
+	case int:
+		return value != 0
+	case int64:
+		return value != 0
+	case float64:
+		return value != 0
+	case string:
+		switch strings.ToLower(strings.TrimSpace(value)) {
+		case "1", "true", "yes", "on":
+			return true
+		case "0", "false", "no", "off":
+			return false
+		}
+	}
+	return defaultValue
+}
+
+func runtimeOptionInt64(options map[string]interface{}, key string, defaultValue int64) int64 {
+	if options == nil {
+		return defaultValue
+	}
+	raw, ok := options[key]
+	if !ok || raw == nil {
+		return defaultValue
+	}
+	switch value := raw.(type) {
+	case int:
+		return int64(value)
+	case int32:
+		return int64(value)
+	case int64:
+		return value
+	case float32:
+		return int64(value)
+	case float64:
+		return int64(value)
+	case string:
+		value = strings.TrimSpace(value)
+		if value == "" {
+			return defaultValue
+		}
+		var parsed int64
+		if _, err := fmt.Sscanf(value, "%d", &parsed); err == nil {
+			return parsed
+		}
+	}
+	return defaultValue
+}
+
+func runtimeOptionHasKey(options map[string]interface{}, key string) bool {
+	if options == nil {
+		return false
+	}
+	_, exists := options[key]
+	return exists
+}
+
+func decodeRuntimeBytesString(input, encoding string) ([]byte, error) {
+	switch strings.ToLower(strings.TrimSpace(encoding)) {
+	case "", "utf8", "utf-8", "text":
+		return []byte(input), nil
+	case "base64":
+		decoded, err := base64.StdEncoding.DecodeString(strings.TrimSpace(input))
+		if err != nil {
+			return nil, fmt.Errorf("invalid base64 data: %w", err)
+		}
+		return decoded, nil
+	case "hex":
+		decoded, err := hex.DecodeString(strings.TrimSpace(input))
+		if err != nil {
+			return nil, fmt.Errorf("invalid hex data: %w", err)
+		}
+		return decoded, nil
+	default:
+		return nil, fmt.Errorf("unsupported byte encoding: %s", encoding)
+	}
+}
+
+func decodeRuntimeBytesValue(raw interface{}, encoding string) ([]byte, error) {
+	switch value := raw.(type) {
+	case string:
+		return decodeRuntimeBytesString(value, encoding)
+	case []byte:
+		cloned := make([]byte, len(value))
+		copy(cloned, value)
+		return cloned, nil
+	case []interface{}:
+		decoded := make([]byte, len(value))
+		for i, item := range value {
+			switch num := item.(type) {
+			case int:
+				decoded[i] = byte(num)
+			case int64:
+				decoded[i] = byte(num)
+			case float64:
+				decoded[i] = byte(int(num))
+			default:
+				return nil, fmt.Errorf("unsupported byte array item at index %d", i)
+			}
+		}
+		return decoded, nil
+	default:
+		return nil, fmt.Errorf("unsupported byte payload type")
+	}
+}
+
+func encodeRuntimeBytes(data []byte, encoding string) (string, error) {
+	switch strings.ToLower(strings.TrimSpace(encoding)) {
+	case "", "base64":
+		return base64.StdEncoding.EncodeToString(data), nil
+	case "hex":
+		return hex.EncodeToString(data), nil
+	case "utf8", "utf-8", "text":
+		return string(data), nil
+	default:
+		return "", fmt.Errorf("unsupported byte encoding: %s", encoding)
+	}
+}
+
+func parseRuntimeBlockCipherOptions(options map[string]interface{}) (*runtimeBlockCipherOptions, error) {
+	parsed := &runtimeBlockCipherOptions{
+		Algorithm:      strings.ToLower(runtimeOptionString(options, "algorithm", "")),
+		Mode:           strings.ToLower(runtimeOptionString(options, "mode", "cbc")),
+		InputEncoding:  strings.ToLower(runtimeOptionString(options, "inputEncoding", "base64")),
+		OutputEncoding: strings.ToLower(runtimeOptionString(options, "outputEncoding", "base64")),
+		Padding:        strings.ToLower(runtimeOptionString(options, "padding", "none")),
+	}
+	if parsed.Algorithm == "" {
+		return nil, fmt.Errorf("algorithm is required")
+	}
+	if parsed.Mode == "" {
+		return nil, fmt.Errorf("mode is required")
+	}
+
+	key, err := decodeRuntimeBytesString(runtimeOptionString(options, "key", ""), runtimeOptionString(options, "keyEncoding", "utf8"))
+	if err != nil {
+		return nil, fmt.Errorf("invalid key: %w", err)
+	}
+	if len(key) == 0 {
+		return nil, fmt.Errorf("key is required")
+	}
+	parsed.Key = key
+
+	iv, err := decodeRuntimeBytesString(runtimeOptionString(options, "iv", ""), runtimeOptionString(options, "ivEncoding", "utf8"))
+	if err != nil {
+		return nil, fmt.Errorf("invalid iv: %w", err)
+	}
+	parsed.IV = iv
+	return parsed, nil
+}
+
+func newRuntimeBlockCipher(options *runtimeBlockCipherOptions) (cipher.Block, error) {
+	switch options.Algorithm {
+	case "blowfish":
+		return blowfish.NewCipher(options.Key)
+	case "aes":
+		return aes.NewCipher(options.Key)
+	default:
+		return nil, fmt.Errorf("unsupported block cipher algorithm: %s", options.Algorithm)
+	}
+}
+
+func applyPKCS7Padding(data []byte, blockSize int) []byte {
+	padding := blockSize - (len(data) % blockSize)
+	if padding == 0 {
+		padding = blockSize
+	}
+	out := make([]byte, len(data)+padding)
+	copy(out, data)
+	for i := len(data); i < len(out); i++ {
+		out[i] = byte(padding)
+	}
+	return out
+}
+
+func removePKCS7Padding(data []byte, blockSize int) ([]byte, error) {
+	if len(data) == 0 || len(data)%blockSize != 0 {
+		return nil, fmt.Errorf("invalid padded payload length")
+	}
+	padding := int(data[len(data)-1])
+	if padding <= 0 || padding > blockSize || padding > len(data) {
+		return nil, fmt.Errorf("invalid PKCS7 padding")
+	}
+	for i := len(data) - padding; i < len(data); i++ {
+		if int(data[i]) != padding {
+			return nil, fmt.Errorf("invalid PKCS7 padding")
+		}
+	}
+	return data[:len(data)-padding], nil
+}
+
+func (r *extensionRuntime) transformBlockCipher(call goja.FunctionCall, decrypt bool) goja.Value {
+	if len(call.Arguments) < 2 {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   "data and options are required",
+		})
+	}
+
+	options := parseRuntimeOptionsArgument(call, 1)
+	parsedOptions, err := parseRuntimeBlockCipherOptions(options)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+	if parsedOptions.Mode != "cbc" {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("unsupported block cipher mode: %s", parsedOptions.Mode),
+		})
+	}
+
+	inputData, err := decodeRuntimeBytesValue(call.Arguments[0].Export(), parsedOptions.InputEncoding)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	block, err := newRuntimeBlockCipher(parsedOptions)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	if len(parsedOptions.IV) != block.BlockSize() {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("iv must be %d bytes for %s", block.BlockSize(), parsedOptions.Algorithm),
+		})
+	}
+
+	data := inputData
+	if !decrypt && parsedOptions.Padding == "pkcs7" {
+		data = applyPKCS7Padding(data, block.BlockSize())
+	}
+	if len(data)%block.BlockSize() != 0 {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("input length must be a multiple of %d bytes", block.BlockSize()),
+		})
+	}
+
+	output := make([]byte, len(data))
+	if decrypt {
+		cipher.NewCBCDecrypter(block, parsedOptions.IV).CryptBlocks(output, data)
+		if parsedOptions.Padding == "pkcs7" {
+			output, err = removePKCS7Padding(output, block.BlockSize())
+			if err != nil {
+				return r.vm.ToValue(map[string]interface{}{
+					"success": false,
+					"error":   err.Error(),
+				})
+			}
+		}
+	} else {
+		cipher.NewCBCEncrypter(block, parsedOptions.IV).CryptBlocks(output, data)
+	}
+
+	encoded, err := encodeRuntimeBytes(output, parsedOptions.OutputEncoding)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	return r.vm.ToValue(map[string]interface{}{
+		"success":    true,
+		"data":       encoded,
+		"block_size": block.BlockSize(),
+	})
+}
+
+func (r *extensionRuntime) encryptBlockCipher(call goja.FunctionCall) goja.Value {
+	return r.transformBlockCipher(call, false)
+}
+
+func (r *extensionRuntime) decryptBlockCipher(call goja.FunctionCall) goja.Value {
+	return r.transformBlockCipher(call, true)
+}

go_backend/extension_runtime_binary_test.go

@@ -0,0 +1,185 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/dop251/goja"
+)
+
+func newBinaryTestRuntime(t *testing.T, withFilePermission bool) *goja.Runtime {
+	t.Helper()
+
+	ext := &loadedExtension{
+		ID: "binary-test-ext",
+		Manifest: &ExtensionManifest{
+			Name: "binary-test-ext",
+			Permissions: ExtensionPermissions{
+				File: withFilePermission,
+			},
+		},
+		DataDir: t.TempDir(),
+	}
+
+	runtime := newExtensionRuntime(ext)
+	vm := goja.New()
+	runtime.RegisterAPIs(vm)
+	return vm
+}
+
+func decodeJSONResult[T any](t *testing.T, value goja.Value) T {
+	t.Helper()
+
+	var decoded T
+	if err := json.Unmarshal([]byte(value.String()), &decoded); err != nil {
+		t.Fatalf("failed to decode JSON result: %v", err)
+	}
+	return decoded
+}
+
+func TestExtensionRuntime_FileByteAPIs(t *testing.T) {
+	vm := newBinaryTestRuntime(t, true)
+
+	result, err := vm.RunString(`
+		(function() {
+			var first = file.writeBytes("bytes.bin", "AAEC", {encoding: "base64", truncate: true});
+			if (!first.success) throw new Error(first.error);
+
+			var second = file.writeBytes("bytes.bin", "0304ff", {encoding: "hex", append: true});
+			if (!second.success) throw new Error(second.error);
+
+			var all = file.readBytes("bytes.bin", {encoding: "hex"});
+			if (!all.success) throw new Error(all.error);
+
+			var slice = file.readBytes("bytes.bin", {offset: 2, length: 2, encoding: "hex"});
+			if (!slice.success) throw new Error(slice.error);
+
+			var tail = file.readBytes("bytes.bin", {offset: 6, length: 4, encoding: "hex"});
+			if (!tail.success) throw new Error(tail.error);
+
+			return JSON.stringify({
+				all: all.data,
+				slice: slice.data,
+				size: all.size,
+				sliceBytes: slice.bytes_read,
+				sliceEof: slice.eof,
+				tailBytes: tail.bytes_read,
+				tailEof: tail.eof
+			});
+		})()
+	`)
+	if err != nil {
+		t.Fatalf("file byte APIs failed: %v", err)
+	}
+
+	decoded := decodeJSONResult[struct {
+		All        string `json:"all"`
+		Slice      string `json:"slice"`
+		Size       int64  `json:"size"`
+		SliceBytes int    `json:"sliceBytes"`
+		SliceEof   bool   `json:"sliceEof"`
+		TailBytes  int    `json:"tailBytes"`
+		TailEof    bool   `json:"tailEof"`
+	}](t, result)
+
+	if decoded.All != "0001020304ff" {
+		t.Fatalf("all = %q", decoded.All)
+	}
+	if decoded.Slice != "0203" {
+		t.Fatalf("slice = %q", decoded.Slice)
+	}
+	if decoded.Size != 6 {
+		t.Fatalf("size = %d", decoded.Size)
+	}
+	if decoded.SliceBytes != 2 {
+		t.Fatalf("slice bytes = %d", decoded.SliceBytes)
+	}
+	if decoded.SliceEof {
+		t.Fatal("slice should not be EOF")
+	}
+	if decoded.TailBytes != 0 || !decoded.TailEof {
+		t.Fatalf("tail read mismatch: bytes=%d eof=%v", decoded.TailBytes, decoded.TailEof)
+	}
+}
+
+func TestExtensionRuntime_BlockCipherCBCSupportsBlowfish(t *testing.T) {
+	vm := newBinaryTestRuntime(t, false)
+
+	result, err := vm.RunString(`
+		(function() {
+			var options = {
+				algorithm: "blowfish",
+				mode: "cbc",
+				key: "0123456789ABCDEFF0E1D2C3B4A59687",
+				keyEncoding: "hex",
+				iv: "0001020304050607",
+				ivEncoding: "hex",
+				inputEncoding: "hex",
+				outputEncoding: "hex",
+				padding: "none"
+			};
+			var enc = utils.encryptBlockCipher("00112233445566778899aabbccddeeff", options);
+			if (!enc.success) throw new Error(enc.error);
+			var dec = utils.decryptBlockCipher(enc.data, options);
+			if (!dec.success) throw new Error(dec.error);
+			return JSON.stringify({enc: enc.data, dec: dec.data});
+		})()
+	`)
+	if err != nil {
+		t.Fatalf("blowfish block cipher failed: %v", err)
+	}
+
+	decoded := decodeJSONResult[struct {
+		Enc string `json:"enc"`
+		Dec string `json:"dec"`
+	}](t, result)
+
+	if decoded.Dec != "00112233445566778899aabbccddeeff" {
+		t.Fatalf("dec = %q", decoded.Dec)
+	}
+	if decoded.Enc == decoded.Dec {
+		t.Fatal("expected ciphertext to differ from plaintext")
+	}
+}
+
+func TestExtensionRuntime_BlockCipherCBCSupportsAES(t *testing.T) {
+	vm := newBinaryTestRuntime(t, false)
+
+	result, err := vm.RunString(`
+		(function() {
+			var options = {
+				algorithm: "aes",
+				mode: "cbc",
+				key: "000102030405060708090a0b0c0d0e0f",
+				keyEncoding: "hex",
+				iv: "0f0e0d0c0b0a09080706050403020100",
+				ivEncoding: "hex",
+				inputEncoding: "utf8",
+				outputEncoding: "base64",
+				padding: "pkcs7"
+			};
+			var enc = utils.encryptBlockCipher("hello generic cbc", options);
+			if (!enc.success) throw new Error(enc.error);
+			var dec = utils.decryptBlockCipher(enc.data, {
+				algorithm: "aes",
+				mode: "cbc",
+				key: options.key,
+				keyEncoding: options.keyEncoding,
+				iv: options.iv,
+				ivEncoding: options.ivEncoding,
+				inputEncoding: "base64",
+				outputEncoding: "utf8",
+				padding: "pkcs7"
+			});
+			if (!dec.success) throw new Error(dec.error);
+			return dec.data;
+		})()
+	`)
+	if err != nil {
+		t.Fatalf("aes block cipher failed: %v", err)
+	}
+
+	if result.String() != "hello generic cbc" {
+		t.Fatalf("unexpected decrypted value: %q", result.String())
+	}
+}

go_backend/extension_runtime_ffmpeg.go

@@ -1,4 +1,3 @@
-// Package gobackend provides FFmpeg API for extension runtime
 package gobackend
 
 import (
@@ -10,9 +9,7 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== FFmpeg API (Post-Processing) ====================
-
-// FFmpegCommand holds a pending FFmpeg command for Flutter to execute
+// FFmpegCommand holds a pending FFmpeg command for Flutter to execute.
 type FFmpegCommand struct {
 	ExtensionID string
 	Command     string
@@ -24,7 +21,6 @@ type FFmpegCommand struct {
 	Output      string
 }
 
-// Global FFmpeg command queue
 var (
 	ffmpegCommands   = make(map[string]*FFmpegCommand)
 	ffmpegCommandsMu sync.RWMutex
@@ -54,7 +50,7 @@ func ClearFFmpegCommand(commandID string) {
 	delete(ffmpegCommands, commandID)
 }
 
-func (r *ExtensionRuntime) ffmpegExecute(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) ffmpegExecute(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -64,7 +60,6 @@ func (r *ExtensionRuntime) ffmpegExecute(call goja.FunctionCall) goja.Value {
 
 	command := call.Arguments[0].String()
 
-	// Generate unique command ID
 	ffmpegCommandsMu.Lock()
 	ffmpegCommandID++
 	cmdID := fmt.Sprintf("%s_%d", r.extensionID, ffmpegCommandID)
@@ -77,7 +72,6 @@ func (r *ExtensionRuntime) ffmpegExecute(call goja.FunctionCall) goja.Value {
 
 	GoLog("[Extension:%s] FFmpeg command queued: %s\n", r.extensionID, cmdID)
 
-	// Wait for completion (with timeout)
 	timeout := 5 * time.Minute
 	start := time.Now()
 	for {
@@ -97,7 +91,6 @@ func (r *ExtensionRuntime) ffmpegExecute(call goja.FunctionCall) goja.Value {
 			}
 			ffmpegCommandsMu.RUnlock()
 
-			// Cleanup
 			ClearFFmpegCommand(cmdID)
 			return r.vm.ToValue(result)
 		}
@@ -114,7 +107,7 @@ func (r *ExtensionRuntime) ffmpegExecute(call goja.FunctionCall) goja.Value {
 	}
 }
 
-func (r *ExtensionRuntime) ffmpegGetInfo(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) ffmpegGetInfo(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -124,7 +117,6 @@ func (r *ExtensionRuntime) ffmpegGetInfo(call goja.FunctionCall) goja.Value {
 
 	filePath := call.Arguments[0].String()
 
-	// Use Go's built-in audio quality function
 	quality, err := GetAudioQuality(filePath)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -142,7 +134,7 @@ func (r *ExtensionRuntime) ffmpegGetInfo(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) ffmpegConvert(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) ffmpegConvert(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -153,7 +145,6 @@ func (r *ExtensionRuntime) ffmpegConvert(call goja.FunctionCall) goja.Value {
 	inputPath := call.Arguments[0].String()
 	outputPath := call.Arguments[1].String()
 
-	// Get options if provided
 	options := map[string]interface{}{}
 	if len(call.Arguments) > 2 && !goja.IsUndefined(call.Arguments[2]) && !goja.IsNull(call.Arguments[2]) {
 		if opts, ok := call.Arguments[2].Export().(map[string]interface{}); ok {
@@ -161,36 +152,29 @@ func (r *ExtensionRuntime) ffmpegConvert(call goja.FunctionCall) goja.Value {
 		}
 	}
 
-	// Build FFmpeg command
 	var cmdParts []string
 	cmdParts = append(cmdParts, "-i", fmt.Sprintf("%q", inputPath))
 
-	// Audio codec
 	if codec, ok := options["codec"].(string); ok {
 		cmdParts = append(cmdParts, "-c:a", codec)
 	}
 
-	// Bitrate
 	if bitrate, ok := options["bitrate"].(string); ok {
 		cmdParts = append(cmdParts, "-b:a", bitrate)
 	}
 
-	// Sample rate
 	if sampleRate, ok := options["sample_rate"].(float64); ok {
 		cmdParts = append(cmdParts, "-ar", fmt.Sprintf("%d", int(sampleRate)))
 	}
 
-	// Channels
 	if channels, ok := options["channels"].(float64); ok {
 		cmdParts = append(cmdParts, "-ac", fmt.Sprintf("%d", int(channels)))
 	}
 
-	// Overwrite output
 	cmdParts = append(cmdParts, "-y", fmt.Sprintf("%q", outputPath))
 
 	command := strings.Join(cmdParts, " ")
 
-	// Execute via ffmpegExecute
 	execCall := goja.FunctionCall{
 		Arguments: []goja.Value{r.vm.ToValue(command)},
 	}

go_backend/extension_runtime_file.go

@@ -1,4 +1,3 @@
-// Package gobackend provides File API for extension runtime
 package gobackend
 
 import (
@@ -13,9 +12,6 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== File API (Sandboxed) ====================
-
-// List of allowed directories for file operations (set by Go backend for download operations)
 var (
 	allowedDownloadDirs   []string
 	allowedDownloadDirsMu sync.RWMutex
@@ -42,18 +38,40 @@ func isPathInAllowedDirs(absPath string) bool {
 	defer allowedDownloadDirsMu.RUnlock()
 
 	for _, allowedDir := range allowedDownloadDirs {
-		if strings.HasPrefix(absPath, allowedDir) {
+		if isPathWithinBase(allowedDir, absPath) {
 			return true
 		}
 	}
 	return false
 }
 
-// validatePath checks if the path is within the extension's sandbox
-// Security: Absolute paths are BLOCKED unless they're in allowed download directories
-// Extensions should use relative paths for their own data storage
-func (r *ExtensionRuntime) validatePath(path string) (string, error) {
-	// Check if extension has file permission
+func isPathWithinBase(baseDir, targetPath string) bool {
+	baseAbs, err := filepath.Abs(baseDir)
+	if err != nil {
+		return false
+	}
+	targetAbs, err := filepath.Abs(targetPath)
+	if err != nil {
+		return false
+	}
+
+	rel, err := filepath.Rel(baseAbs, targetAbs)
+	if err != nil {
+		return false
+	}
+	rel = filepath.Clean(rel)
+	if rel == "." {
+		return true
+	}
+
+	prefix := ".." + string(filepath.Separator)
+	if rel == ".." || strings.HasPrefix(rel, prefix) {
+		return false
+	}
+	return true
+}
+
+func (r *extensionRuntime) validatePath(path string) (string, error) {
 	if !r.manifest.Permissions.File {
 		return "", fmt.Errorf("file access denied: extension does not have 'file' permission")
 	}
@@ -81,14 +99,14 @@ func (r *ExtensionRuntime) validatePath(path string) (string, error) {
 	}
 
 	absDataDir, _ := filepath.Abs(r.dataDir)
-	if !strings.HasPrefix(absPath, absDataDir) {
+	if !isPathWithinBase(absDataDir, absPath) {
 		return "", fmt.Errorf("file access denied: path '%s' is outside sandbox", path)
 	}
 
 	return absPath, nil
 }
 
-func (r *ExtensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -156,7 +174,12 @@ func (r *ExtensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
 		req.Header.Set("User-Agent", "SpotiFLAC-Extension/1.0")
 	}
 
-	resp, err := r.httpClient.Do(req)
+	client := r.downloadClient
+	if client == nil {
+		client = r.httpClient
+	}
+
+	resp, err := client.Do(req)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -182,13 +205,22 @@ func (r *ExtensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
 	defer out.Close()
 
 	contentLength := resp.ContentLength
+	activeItemID := r.getActiveDownloadItemID()
+	if activeItemID != "" && contentLength > 0 {
+		SetItemBytesTotal(activeItemID, contentLength)
+	}
+
+	var progressWriter interface{ Write([]byte) (int, error) } = out
+	if activeItemID != "" {
+		progressWriter = NewItemProgressWriter(out, activeItemID)
+	}
 
 	var written int64
 	buf := make([]byte, 32*1024)
 	for {
 		nr, er := resp.Body.Read(buf)
 		if nr > 0 {
-			nw, ew := out.Write(buf[0:nr])
+			nw, ew := progressWriter.Write(buf[0:nr])
 			if nw < 0 || nr < nw {
 				nw = 0
 				if ew == nil {
@@ -197,6 +229,12 @@ func (r *ExtensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
 			}
 			written += int64(nw)
 			if ew != nil {
+				if ew == ErrDownloadCancelled {
+					return r.vm.ToValue(map[string]interface{}{
+						"success": false,
+						"error":   "download cancelled",
+					})
+				}
 				return r.vm.ToValue(map[string]interface{}{
 					"success": false,
 					"error":   fmt.Sprintf("failed to write file: %v", ew),
@@ -233,7 +271,7 @@ func (r *ExtensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) fileExists(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileExists(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
 	}
@@ -248,7 +286,7 @@ func (r *ExtensionRuntime) fileExists(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(err == nil)
 }
 
-func (r *ExtensionRuntime) fileDelete(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileDelete(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -277,7 +315,7 @@ func (r *ExtensionRuntime) fileDelete(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) fileRead(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileRead(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -308,7 +346,105 @@ func (r *ExtensionRuntime) fileRead(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) fileWrite(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileReadBytes(call goja.FunctionCall) goja.Value {
+	if len(call.Arguments) < 1 {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   "path is required",
+		})
+	}
+
+	path := call.Arguments[0].String()
+	fullPath, err := r.validatePath(path)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	options := parseRuntimeOptionsArgument(call, 1)
+	offset := runtimeOptionInt64(options, "offset", 0)
+	length := runtimeOptionInt64(options, "length", -1)
+	encoding := runtimeOptionString(options, "encoding", "base64")
+	if offset < 0 {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   "offset must be >= 0",
+		})
+	}
+
+	file, err := os.Open(fullPath)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+	defer file.Close()
+
+	info, err := file.Stat()
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	size := info.Size()
+	if offset > size {
+		offset = size
+	}
+	if _, err := file.Seek(offset, io.SeekStart); err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("failed to seek file: %v", err),
+		})
+	}
+
+	var data []byte
+	switch {
+	case length == 0:
+		data = []byte{}
+	case length > 0:
+		buf := make([]byte, int(length))
+		n, readErr := file.Read(buf)
+		if readErr != nil && readErr != io.EOF {
+			return r.vm.ToValue(map[string]interface{}{
+				"success": false,
+				"error":   fmt.Sprintf("failed to read file: %v", readErr),
+			})
+		}
+		data = buf[:n]
+	default:
+		data, err = io.ReadAll(file)
+		if err != nil {
+			return r.vm.ToValue(map[string]interface{}{
+				"success": false,
+				"error":   fmt.Sprintf("failed to read file: %v", err),
+			})
+		}
+	}
+
+	encoded, err := encodeRuntimeBytes(data, encoding)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	return r.vm.ToValue(map[string]interface{}{
+		"success":    true,
+		"data":       encoded,
+		"bytes_read": len(data),
+		"offset":     offset,
+		"size":       size,
+		"eof":        offset+int64(len(data)) >= size,
+	})
+}
+
+func (r *extensionRuntime) fileWrite(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -327,7 +463,6 @@ func (r *ExtensionRuntime) fileWrite(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	// Create directory if needed
 	dir := filepath.Dir(fullPath)
 	if err := os.MkdirAll(dir, 0755); err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -349,7 +484,108 @@ func (r *ExtensionRuntime) fileWrite(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) fileCopy(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileWriteBytes(call goja.FunctionCall) goja.Value {
+	if len(call.Arguments) < 2 {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   "path and data are required",
+		})
+	}
+
+	path := call.Arguments[0].String()
+	fullPath, err := r.validatePath(path)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	options := parseRuntimeOptionsArgument(call, 2)
+	appendMode := runtimeOptionBool(options, "append", false)
+	truncate := runtimeOptionBool(options, "truncate", false)
+	hasOffset := runtimeOptionHasKey(options, "offset")
+	offset := runtimeOptionInt64(options, "offset", 0)
+	encoding := runtimeOptionString(options, "encoding", "base64")
+
+	if appendMode && hasOffset {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   "append and offset cannot be used together",
+		})
+	}
+	if offset < 0 {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   "offset must be >= 0",
+		})
+	}
+
+	data, err := decodeRuntimeBytesValue(call.Arguments[1].Export(), encoding)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	dir := filepath.Dir(fullPath)
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("failed to create directory: %v", err),
+		})
+	}
+
+	flags := os.O_CREATE | os.O_WRONLY
+	if appendMode {
+		flags |= os.O_APPEND
+	}
+	if truncate {
+		flags |= os.O_TRUNC
+	}
+
+	file, err := os.OpenFile(fullPath, flags, 0644)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+	defer file.Close()
+
+	if hasOffset && !appendMode {
+		if _, err := file.Seek(offset, io.SeekStart); err != nil {
+			return r.vm.ToValue(map[string]interface{}{
+				"success": false,
+				"error":   fmt.Sprintf("failed to seek file: %v", err),
+			})
+		}
+	}
+
+	written, err := file.Write(data)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	info, statErr := file.Stat()
+	size := int64(0)
+	if statErr == nil {
+		size = info.Size()
+	}
+
+	return r.vm.ToValue(map[string]interface{}{
+		"success":       true,
+		"path":          fullPath,
+		"bytes_written": written,
+		"size":          size,
+	})
+}
+
+func (r *extensionRuntime) fileCopy(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -376,13 +612,14 @@ func (r *ExtensionRuntime) fileCopy(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	data, err := os.ReadFile(fullSrc)
+	srcFile, err := os.Open(fullSrc)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
 			"error":   fmt.Sprintf("failed to read source: %v", err),
 		})
 	}
+	defer srcFile.Close()
 
 	dir := filepath.Dir(fullDst)
 	if err := os.MkdirAll(dir, 0755); err != nil {
@@ -392,10 +629,26 @@ func (r *ExtensionRuntime) fileCopy(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	if err := os.WriteFile(fullDst, data, 0644); err != nil {
+	dstFile, err := os.OpenFile(fullDst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0644)
+	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
-			"error":   fmt.Sprintf("failed to write destination: %v", err),
+			"error":   fmt.Sprintf("failed to open destination: %v", err),
+		})
+	}
+
+	if _, err := io.Copy(dstFile, srcFile); err != nil {
+		_ = dstFile.Close()
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("failed to copy file: %v", err),
+		})
+	}
+
+	if err := dstFile.Close(); err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("failed to finalize destination: %v", err),
 		})
 	}
 
@@ -405,7 +658,7 @@ func (r *ExtensionRuntime) fileCopy(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) fileMove(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileMove(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -453,7 +706,7 @@ func (r *ExtensionRuntime) fileMove(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) fileGetSize(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileGetSize(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,

go_backend/extension_runtime_http.go

@@ -1,4 +1,3 @@
-// Package gobackend provides HTTP API for extension runtime
 package gobackend
 
 import (
@@ -12,25 +11,33 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== HTTP API (Sandboxed) ====================
-
-// HTTPResponse represents the response from an HTTP request
 type HTTPResponse struct {
 	StatusCode int               `json:"statusCode"`
 	Body       string            `json:"body"`
 	Headers    map[string]string `json:"headers"`
 }
 
-// validateDomain checks if the domain is allowed by the extension's permissions
-func (r *ExtensionRuntime) validateDomain(urlStr string) error {
+func (r *extensionRuntime) validateDomain(urlStr string) error {
 	parsed, err := url.Parse(urlStr)
 	if err != nil {
 		return fmt.Errorf("invalid URL: %w", err)
 	}
 
-	domain := parsed.Hostname()
+	if parsed.Scheme == "" {
+		return fmt.Errorf("invalid URL: scheme is required")
+	}
+	if parsed.Scheme != "https" {
+		return fmt.Errorf("network access denied: only https is allowed")
+	}
+	if parsed.User != nil {
+		return fmt.Errorf("invalid URL: embedded credentials are not allowed")
+	}
+
+	domain := parsed.Hostname()
+	if domain == "" {
+		return fmt.Errorf("invalid URL: hostname is required")
+	}
 
-	// Block private/local network access (SSRF protection)
 	if isPrivateIP(domain) {
 		return fmt.Errorf("network access denied: private/local network '%s' not allowed", domain)
 	}
@@ -42,8 +49,7 @@ func (r *ExtensionRuntime) validateDomain(urlStr string) error {
 	return nil
 }
 
-// httpGet performs a GET request (sandboxed)
-func (r *ExtensionRuntime) httpGet(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpGet(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"error": "URL is required",
@@ -76,16 +82,14 @@ func (r *ExtensionRuntime) httpGet(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	// Set headers - user headers first
 	for k, v := range headers {
 		req.Header.Set(k, v)
 	}
-	// Only set default User-Agent if not provided by extension
+
 	if req.Header.Get("User-Agent") == "" {
 		req.Header.Set("User-Agent", "Spotiflac-Extension/1.0")
 	}
 
-	// Execute request
 	resp, err := r.httpClient.Do(req)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -101,27 +105,26 @@ func (r *ExtensionRuntime) httpGet(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	// Extract response headers - return all values as arrays for multi-value headers (cookies, etc.)
 	respHeaders := make(map[string]interface{})
 	for k, v := range resp.Header {
 		if len(v) == 1 {
 			respHeaders[k] = v[0]
 		} else {
-			respHeaders[k] = v // Return as array if multiple values
+			respHeaders[k] = v
 		}
 	}
 
 	return r.vm.ToValue(map[string]interface{}{
 		"statusCode": resp.StatusCode,
-		"status":     resp.StatusCode, // Alias for convenience
+		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
+		"url":        resp.Request.URL.String(),
 		"body":       string(body),
 		"headers":    respHeaders,
 	})
 }
 
-// httpPost performs a POST request (sandboxed)
-func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"error": "URL is required",
@@ -137,7 +140,6 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	// Get body if provided - support both string and object
 	var bodyStr string
 	if len(call.Arguments) > 1 && !goja.IsUndefined(call.Arguments[1]) && !goja.IsNull(call.Arguments[1]) {
 		bodyArg := call.Arguments[1].Export()
@@ -145,7 +147,6 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 		case string:
 			bodyStr = v
 		case map[string]interface{}, []interface{}:
-			// Auto-stringify objects and arrays to JSON
 			jsonBytes, err := json.Marshal(v)
 			if err != nil {
 				return r.vm.ToValue(map[string]interface{}{
@@ -154,12 +155,10 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 			}
 			bodyStr = string(jsonBytes)
 		default:
-			// Fallback to string conversion
 			bodyStr = call.Arguments[1].String()
 		}
 	}
 
-	// Get headers if provided
 	headers := make(map[string]string)
 	if len(call.Arguments) > 2 && !goja.IsUndefined(call.Arguments[2]) && !goja.IsNull(call.Arguments[2]) {
 		headersObj := call.Arguments[2].Export()
@@ -177,11 +176,10 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	// Set headers - user headers first
 	for k, v := range headers {
 		req.Header.Set(k, v)
 	}
-	// Only set defaults if not provided by extension
+
 	if req.Header.Get("User-Agent") == "" {
 		req.Header.Set("User-Agent", "Spotiflac-Extension/1.0")
 	}
@@ -189,7 +187,6 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 		req.Header.Set("Content-Type", "application/json")
 	}
 
-	// Execute request
 	resp, err := r.httpClient.Do(req)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -205,26 +202,26 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	// Extract response headers - return all values as arrays for multi-value headers
 	respHeaders := make(map[string]interface{})
 	for k, v := range resp.Header {
 		if len(v) == 1 {
 			respHeaders[k] = v[0]
 		} else {
-			respHeaders[k] = v // Return as array if multiple values
+			respHeaders[k] = v
 		}
 	}
 
 	return r.vm.ToValue(map[string]interface{}{
 		"statusCode": resp.StatusCode,
-		"status":     resp.StatusCode, // Alias for convenience
+		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
+		"url":        resp.Request.URL.String(),
 		"body":       string(body),
 		"headers":    respHeaders,
 	})
 }
 
-func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"error": "URL is required",
@@ -240,27 +237,22 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	// Default options
 	method := "GET"
 	var bodyStr string
 	headers := make(map[string]string)
 
-	// Parse options if provided
 	if len(call.Arguments) > 1 && !goja.IsUndefined(call.Arguments[1]) && !goja.IsNull(call.Arguments[1]) {
 		optionsObj := call.Arguments[1].Export()
 		if opts, ok := optionsObj.(map[string]interface{}); ok {
-			// Get method
 			if m, ok := opts["method"].(string); ok {
 				method = strings.ToUpper(m)
 			}
 
-			// Get body - support both string and object
 			if bodyArg, ok := opts["body"]; ok && bodyArg != nil {
 				switch v := bodyArg.(type) {
 				case string:
 					bodyStr = v
 				case map[string]interface{}, []interface{}:
-					// Auto-stringify objects and arrays to JSON
 					jsonBytes, err := json.Marshal(v)
 					if err != nil {
 						return r.vm.ToValue(map[string]interface{}{
@@ -273,7 +265,6 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 				}
 			}
 
-			// Get headers
 			if h, ok := opts["headers"].(map[string]interface{}); ok {
 				for k, v := range h {
 					headers[k] = fmt.Sprintf("%v", v)
@@ -282,7 +273,6 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 		}
 	}
 
-	// Create request
 	var reqBody io.Reader
 	if bodyStr != "" {
 		reqBody = strings.NewReader(bodyStr)
@@ -295,11 +285,10 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	// Set headers - user headers first
 	for k, v := range headers {
 		req.Header.Set(k, v)
 	}
-	// Only set defaults if not provided by extension
+
 	if req.Header.Get("User-Agent") == "" {
 		req.Header.Set("User-Agent", "Spotiflac-Extension/1.0")
 	}
@@ -307,7 +296,6 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 		req.Header.Set("Content-Type", "application/json")
 	}
 
-	// Execute request
 	resp, err := r.httpClient.Do(req)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -323,42 +311,38 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	// Extract response headers - return all values as arrays for multi-value headers
 	respHeaders := make(map[string]interface{})
 	for k, v := range resp.Header {
 		if len(v) == 1 {
 			respHeaders[k] = v[0]
 		} else {
-			respHeaders[k] = v // Return as array if multiple values
+			respHeaders[k] = v
 		}
 	}
 
-	// Return response with helper properties
 	return r.vm.ToValue(map[string]interface{}{
 		"statusCode": resp.StatusCode,
-		"status":     resp.StatusCode, // Alias for convenience
+		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
+		"url":        resp.Request.URL.String(),
 		"body":       string(body),
 		"headers":    respHeaders,
 	})
 }
 
-func (r *ExtensionRuntime) httpPut(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpPut(call goja.FunctionCall) goja.Value {
 	return r.httpMethodShortcut("PUT", call)
 }
 
-// httpDelete performs a DELETE request (shortcut for http.request with method: "DELETE")
-func (r *ExtensionRuntime) httpDelete(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpDelete(call goja.FunctionCall) goja.Value {
 	return r.httpMethodShortcut("DELETE", call)
 }
 
-func (r *ExtensionRuntime) httpPatch(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpPatch(call goja.FunctionCall) goja.Value {
 	return r.httpMethodShortcut("PATCH", call)
 }
 
-// httpMethodShortcut is a helper for PUT/DELETE/PATCH shortcuts
-// Signature: http.put(url, body, headers) / http.delete(url, headers) / http.patch(url, body, headers)
-func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpMethodShortcut(method string, call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"error": "URL is required",
@@ -377,9 +361,7 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 	var bodyStr string
 	headers := make(map[string]string)
 
-	// For DELETE, second arg is headers; for PUT/PATCH, second arg is body
 	if method == "DELETE" {
-		// http.delete(url, headers)
 		if len(call.Arguments) > 1 && !goja.IsUndefined(call.Arguments[1]) && !goja.IsNull(call.Arguments[1]) {
 			headersObj := call.Arguments[1].Export()
 			if h, ok := headersObj.(map[string]interface{}); ok {
@@ -389,7 +371,6 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 			}
 		}
 	} else {
-		// http.put(url, body, headers) / http.patch(url, body, headers)
 		if len(call.Arguments) > 1 && !goja.IsUndefined(call.Arguments[1]) && !goja.IsNull(call.Arguments[1]) {
 			bodyArg := call.Arguments[1].Export()
 			switch v := bodyArg.(type) {
@@ -418,7 +399,6 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 		}
 	}
 
-	// Create request
 	var reqBody io.Reader
 	if bodyStr != "" {
 		reqBody = strings.NewReader(bodyStr)
@@ -431,7 +411,6 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 		})
 	}
 
-	// Set headers - user headers first
 	for k, v := range headers {
 		req.Header.Set(k, v)
 	}
@@ -442,7 +421,6 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 		req.Header.Set("Content-Type", "application/json")
 	}
 
-	// Execute request
 	resp, err := r.httpClient.Do(req)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -458,7 +436,6 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 		})
 	}
 
-	// Extract response headers
 	respHeaders := make(map[string]interface{})
 	for k, v := range resp.Header {
 		if len(v) == 1 {
@@ -472,12 +449,13 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 		"statusCode": resp.StatusCode,
 		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
+		"url":        resp.Request.URL.String(),
 		"body":       string(body),
 		"headers":    respHeaders,
 	})
 }
 
-func (r *ExtensionRuntime) httpClearCookies(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpClearCookies(call goja.FunctionCall) goja.Value {
 	if jar, ok := r.cookieJar.(*simpleCookieJar); ok {
 		jar.mu.Lock()
 		jar.cookies = make(map[string][]*http.Cookie)

go_backend/extension_runtime_matching.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Track Matching API for extension runtime
 package gobackend
 
 import (
@@ -7,10 +6,7 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== Track Matching API ====================
-
-// matchingCompareStrings compares two strings with fuzzy matching
-func (r *ExtensionRuntime) matchingCompareStrings(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) matchingCompareStrings(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(0.0)
 	}
@@ -22,13 +18,11 @@ func (r *ExtensionRuntime) matchingCompareStrings(call goja.FunctionCall) goja.V
 		return r.vm.ToValue(1.0)
 	}
 
-	// Calculate Levenshtein distance-based similarity
 	similarity := calculateStringSimilarity(str1, str2)
 	return r.vm.ToValue(similarity)
 }
 
-// matchingCompareDuration compares two durations with tolerance
-func (r *ExtensionRuntime) matchingCompareDuration(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) matchingCompareDuration(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(false)
 	}
@@ -36,8 +30,7 @@ func (r *ExtensionRuntime) matchingCompareDuration(call goja.FunctionCall) goja.
 	dur1 := int(call.Arguments[0].ToInteger())
 	dur2 := int(call.Arguments[1].ToInteger())
 
-	// Default tolerance: 3 seconds
-	tolerance := 3000 // milliseconds
+	tolerance := 3000
 	if len(call.Arguments) > 2 && !goja.IsUndefined(call.Arguments[2]) {
 		tolerance = int(call.Arguments[2].ToInteger())
 	}
@@ -50,8 +43,7 @@ func (r *ExtensionRuntime) matchingCompareDuration(call goja.FunctionCall) goja.
 	return r.vm.ToValue(diff <= tolerance)
 }
 
-// matchingNormalizeString normalizes a string for comparison
-func (r *ExtensionRuntime) matchingNormalizeString(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) matchingNormalizeString(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -61,7 +53,6 @@ func (r *ExtensionRuntime) matchingNormalizeString(call goja.FunctionCall) goja.
 	return r.vm.ToValue(normalized)
 }
 
-// calculateStringSimilarity calculates similarity between two strings (0-1)
 func calculateStringSimilarity(s1, s2 string) float64 {
 	if len(s1) == 0 && len(s2) == 0 {
 		return 1.0
@@ -70,7 +61,6 @@ func calculateStringSimilarity(s1, s2 string) float64 {
 		return 0.0
 	}
 
-	// Use Levenshtein distance
 	distance := levenshteinDistance(s1, s2)
 	maxLen := len(s1)
 	if len(s2) > maxLen {
@@ -80,7 +70,6 @@ func calculateStringSimilarity(s1, s2 string) float64 {
 	return 1.0 - float64(distance)/float64(maxLen)
 }
 
-// levenshteinDistance calculates the Levenshtein distance between two strings
 func levenshteinDistance(s1, s2 string) int {
 	if len(s1) == 0 {
 		return len(s2)
@@ -89,7 +78,6 @@ func levenshteinDistance(s1, s2 string) int {
 		return len(s1)
 	}
 
-	// Create matrix
 	matrix := make([][]int, len(s1)+1)
 	for i := range matrix {
 		matrix[i] = make([]int, len(s2)+1)
@@ -99,7 +87,6 @@ func levenshteinDistance(s1, s2 string) int {
 		matrix[0][j] = j
 	}
 
-	// Fill matrix
 	for i := 1; i <= len(s1); i++ {
 		for j := 1; j <= len(s2); j++ {
 			cost := 1
@@ -107,9 +94,9 @@ func levenshteinDistance(s1, s2 string) int {
 				cost = 0
 			}
 			matrix[i][j] = min(
-				matrix[i-1][j]+1,      // deletion
-				matrix[i][j-1]+1,      // insertion
-				matrix[i-1][j-1]+cost, // substitution
+				matrix[i-1][j]+1,
+				matrix[i][j-1]+1,
+				matrix[i-1][j-1]+cost,
 			)
 		}
 	}
@@ -117,12 +104,9 @@ func levenshteinDistance(s1, s2 string) int {
 	return matrix[len(s1)][len(s2)]
 }
 
-// normalizeStringForMatching normalizes a string for comparison
 func normalizeStringForMatching(s string) string {
-	// Convert to lowercase
 	s = strings.ToLower(s)
 
-	// Remove common suffixes/prefixes
 	suffixes := []string{
 		" (remastered)", " (remaster)", " - remastered", " - remaster",
 		" (deluxe)", " (deluxe edition)", " - deluxe", " - deluxe edition",
@@ -136,7 +120,6 @@ func normalizeStringForMatching(s string) string {
 		}
 	}
 
-	// Remove special characters
 	var result strings.Builder
 	for _, r := range s {
 		if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == ' ' {
@@ -144,7 +127,6 @@ func normalizeStringForMatching(s string) string {
 		}
 	}
 
-	// Collapse multiple spaces
 	s = strings.Join(strings.Fields(result.String()), " ")
 
 	return strings.TrimSpace(s)

go_backend/extension_runtime_polyfills.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Browser-like Polyfills for extension runtime
 package gobackend
 
 import (
@@ -13,26 +12,17 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== Browser-like Polyfills ====================
-// These polyfills make porting browser/Node.js libraries easier
-// without compromising sandbox security
-
-// fetchPolyfill implements browser-compatible fetch() API
-// Returns a Promise-like object with json(), text() methods
-func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.createFetchError("URL is required")
 	}
 
 	urlStr := call.Arguments[0].String()
-
-	// Validate domain
 	if err := r.validateDomain(urlStr); err != nil {
 		GoLog("[Extension:%s] fetch blocked: %v\n", r.extensionID, err)
 		return r.createFetchError(err.Error())
 	}
 
-	// Parse options
 	method := "GET"
 	var bodyStr string
 	headers := make(map[string]string)
@@ -40,12 +30,10 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) > 1 && !goja.IsUndefined(call.Arguments[1]) && !goja.IsNull(call.Arguments[1]) {
 		optionsObj := call.Arguments[1].Export()
 		if opts, ok := optionsObj.(map[string]interface{}); ok {
-			// Method
 			if m, ok := opts["method"].(string); ok {
 				method = strings.ToUpper(m)
 			}
 
-			// Body - support string, object (auto-stringify), or nil
 			if bodyArg, ok := opts["body"]; ok && bodyArg != nil {
 				switch v := bodyArg.(type) {
 				case string:
@@ -61,7 +49,6 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 				}
 			}
 
-			// Headers
 			if h, ok := opts["headers"]; ok && h != nil {
 				switch hv := h.(type) {
 				case map[string]interface{}:
@@ -73,7 +60,6 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 		}
 	}
 
-	// Create HTTP request
 	var reqBody io.Reader
 	if bodyStr != "" {
 		reqBody = strings.NewReader(bodyStr)
@@ -84,11 +70,9 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 		return r.createFetchError(err.Error())
 	}
 
-	// Set headers - user headers first
 	for k, v := range headers {
 		req.Header.Set(k, v)
 	}
-	// Set defaults if not provided
 	if req.Header.Get("User-Agent") == "" {
 		req.Header.Set("User-Agent", "SpotiFLAC-Extension/1.0")
 	}
@@ -96,20 +80,17 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 		req.Header.Set("Content-Type", "application/json")
 	}
 
-	// Execute request
 	resp, err := r.httpClient.Do(req)
 	if err != nil {
 		return r.createFetchError(err.Error())
 	}
 	defer resp.Body.Close()
 
-	// Read body
 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
 		return r.createFetchError(err.Error())
 	}
 
-	// Extract response headers
 	respHeaders := make(map[string]interface{})
 	for k, v := range resp.Header {
 		if len(v) == 1 {
@@ -119,23 +100,19 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 		}
 	}
 
-	// Create Response object (browser-compatible)
 	responseObj := r.vm.NewObject()
 	responseObj.Set("ok", resp.StatusCode >= 200 && resp.StatusCode < 300)
 	responseObj.Set("status", resp.StatusCode)
 	responseObj.Set("statusText", http.StatusText(resp.StatusCode))
 	responseObj.Set("headers", respHeaders)
-	responseObj.Set("url", urlStr)
+	responseObj.Set("url", resp.Request.URL.String())
 
-	// Store body for methods
 	bodyString := string(body)
 
-	// text() method - returns body as string
 	responseObj.Set("text", func(call goja.FunctionCall) goja.Value {
 		return r.vm.ToValue(bodyString)
 	})
 
-	// json() method - parses body as JSON
 	responseObj.Set("json", func(call goja.FunctionCall) goja.Value {
 		var result interface{}
 		if err := json.Unmarshal(body, &result); err != nil {
@@ -145,9 +122,7 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 		return r.vm.ToValue(result)
 	})
 
-	// arrayBuffer() method - returns body as array (simplified)
 	responseObj.Set("arrayBuffer", func(call goja.FunctionCall) goja.Value {
-		// Return as array of bytes
 		byteArray := make([]interface{}, len(body))
 		for i, b := range body {
 			byteArray[i] = int(b)
@@ -158,8 +133,7 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 	return responseObj
 }
 
-// createFetchError creates a fetch error response
-func (r *ExtensionRuntime) createFetchError(message string) goja.Value {
+func (r *extensionRuntime) createFetchError(message string) goja.Value {
 	errorObj := r.vm.NewObject()
 	errorObj.Set("ok", false)
 	errorObj.Set("status", 0)
@@ -174,15 +148,13 @@ func (r *ExtensionRuntime) createFetchError(message string) goja.Value {
 	return errorObj
 }
 
-// atobPolyfill implements browser atob() - decode base64 to string
-func (r *ExtensionRuntime) atobPolyfill(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) atobPolyfill(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
 	input := call.Arguments[0].String()
 	decoded, err := base64.StdEncoding.DecodeString(input)
 	if err != nil {
-		// Try URL-safe base64
 		decoded, err = base64.URLEncoding.DecodeString(input)
 		if err != nil {
 			GoLog("[Extension:%s] atob decode error: %v\n", r.extensionID, err)
@@ -192,8 +164,7 @@ func (r *ExtensionRuntime) atobPolyfill(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(string(decoded))
 }
 
-// btoaPolyfill implements browser btoa() - encode string to base64
-func (r *ExtensionRuntime) btoaPolyfill(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) btoaPolyfill(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -201,14 +172,11 @@ func (r *ExtensionRuntime) btoaPolyfill(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(base64.StdEncoding.EncodeToString([]byte(input)))
 }
 
-// registerTextEncoderDecoder registers TextEncoder and TextDecoder classes
-func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
-	// TextEncoder constructor
+func (r *extensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 	vm.Set("TextEncoder", func(call goja.ConstructorCall) *goja.Object {
 		encoder := call.This
 		encoder.Set("encoding", "utf-8")
 
-		// encode() method - string to Uint8Array
 		encoder.Set("encode", func(call goja.FunctionCall) goja.Value {
 			if len(call.Arguments) < 1 {
 				return vm.ToValue([]byte{})
@@ -216,7 +184,6 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 			input := call.Arguments[0].String()
 			bytes := []byte(input)
 
-			// Return as array (Uint8Array-like)
 			result := make([]interface{}, len(bytes))
 			for i, b := range bytes {
 				result[i] = int(b)
@@ -224,9 +191,7 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 			return vm.ToValue(result)
 		})
 
-		// encodeInto() method
 		encoder.Set("encodeInto", func(call goja.FunctionCall) goja.Value {
-			// Simplified implementation
 			if len(call.Arguments) < 2 {
 				return vm.ToValue(map[string]interface{}{"read": 0, "written": 0})
 			}
@@ -240,11 +205,9 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 		return nil
 	})
 
-	// TextDecoder constructor
 	vm.Set("TextDecoder", func(call goja.ConstructorCall) *goja.Object {
 		decoder := call.This
 
-		// Get encoding from arguments (default: utf-8)
 		encoding := "utf-8"
 		if len(call.Arguments) > 0 && !goja.IsUndefined(call.Arguments[0]) {
 			encoding = call.Arguments[0].String()
@@ -253,13 +216,11 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 		decoder.Set("fatal", false)
 		decoder.Set("ignoreBOM", false)
 
-		// decode() method - Uint8Array to string
 		decoder.Set("decode", func(call goja.FunctionCall) goja.Value {
 			if len(call.Arguments) < 1 {
 				return vm.ToValue("")
 			}
 
-			// Handle different input types
 			input := call.Arguments[0].Export()
 			var bytes []byte
 
@@ -279,7 +240,6 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 					}
 				}
 			case string:
-				// Already a string, just return it
 				return vm.ToValue(v)
 			default:
 				return vm.ToValue("")
@@ -292,8 +252,7 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 	})
 }
 
-// registerURLClass registers the URL class for URL parsing
-func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
+func (r *extensionRuntime) registerURLClass(vm *goja.Runtime) {
 	vm.Set("URL", func(call goja.ConstructorCall) *goja.Object {
 		urlObj := call.This
 
@@ -304,7 +263,6 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
 
 		urlStr := call.Arguments[0].String()
 
-		// Handle relative URLs with base
 		if len(call.Arguments) > 1 && !goja.IsUndefined(call.Arguments[1]) {
 			baseStr := call.Arguments[1].String()
 			baseURL, err := url.Parse(baseStr)
@@ -322,7 +280,6 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
 			return nil
 		}
 
-		// Set URL properties
 		urlObj.Set("href", parsed.String())
 		urlObj.Set("protocol", parsed.Scheme+":")
 		urlObj.Set("host", parsed.Host)
@@ -342,10 +299,9 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
 		password, _ := parsed.User.Password()
 		urlObj.Set("password", password)
 
-		// searchParams object
-		searchParams := vm.NewObject()
 		queryValues := parsed.Query()
 
+		searchParams := vm.NewObject()
 		searchParams.Set("get", func(call goja.FunctionCall) goja.Value {
 			if len(call.Arguments) < 1 {
 				return goja.Null()
@@ -379,12 +335,10 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
 
 		urlObj.Set("searchParams", searchParams)
 
-		// toString method
 		urlObj.Set("toString", func(call goja.FunctionCall) goja.Value {
 			return vm.ToValue(parsed.String())
 		})
 
-		// toJSON method
 		urlObj.Set("toJSON", func(call goja.FunctionCall) goja.Value {
 			return vm.ToValue(parsed.String())
 		})
@@ -392,17 +346,14 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
 		return nil
 	})
 
-	// URLSearchParams constructor
 	vm.Set("URLSearchParams", func(call goja.ConstructorCall) *goja.Object {
 		paramsObj := call.This
 		values := url.Values{}
 
-		// Parse initial value if provided
 		if len(call.Arguments) > 0 && !goja.IsUndefined(call.Arguments[0]) {
 			init := call.Arguments[0].Export()
 			switch v := init.(type) {
 			case string:
-				// Parse query string
 				parsed, _ := url.ParseQuery(strings.TrimPrefix(v, "?"))
 				values = parsed
 			case map[string]interface{}:
@@ -465,13 +416,7 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
 	})
 }
 
-// registerJSONGlobal ensures JSON global is properly set up
-func (r *ExtensionRuntime) registerJSONGlobal(vm *goja.Runtime) {
-	// JSON is already built-in to Goja, but we can enhance it
-	// This ensures JSON.parse and JSON.stringify work as expected
-
-	// The built-in JSON object should already work, but let's verify
-	// and add any missing functionality if needed
+func (r *extensionRuntime) registerJSONGlobal(vm *goja.Runtime) {
 	jsonScript := `
 		if (typeof JSON === 'undefined') {
 			var JSON = {

go_backend/extension_runtime_storage.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Storage and Credentials API for extension runtime
 package gobackend
 
 import (
@@ -11,64 +10,180 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"reflect"
+	"time"
 
 	"github.com/dop251/goja"
 )
 
-// ==================== Storage API ====================
+const (
+	defaultStorageFlushDelay = 400 * time.Millisecond
+	storageFlushRetryDelay   = 2 * time.Second
+)
 
-// getStoragePath returns the path to the extension's storage file
-func (r *ExtensionRuntime) getStoragePath() string {
+func (r *extensionRuntime) getStoragePath() string {
 	return filepath.Join(r.dataDir, "storage.json")
 }
 
-// loadStorage loads the storage data from disk
-func (r *ExtensionRuntime) loadStorage() (map[string]interface{}, error) {
+func cloneInterfaceMap(src map[string]interface{}) map[string]interface{} {
+	if len(src) == 0 {
+		return make(map[string]interface{})
+	}
+	dst := make(map[string]interface{}, len(src))
+	for k, v := range src {
+		dst[k] = v
+	}
+	return dst
+}
+
+func (r *extensionRuntime) ensureStorageLoaded() error {
+	r.storageMu.RLock()
+	if r.storageLoaded {
+		r.storageMu.RUnlock()
+		return nil
+	}
+	r.storageMu.RUnlock()
+
+	r.storageMu.Lock()
+	defer r.storageMu.Unlock()
+	if r.storageLoaded {
+		return nil
+	}
+
 	storagePath := r.getStoragePath()
 	data, err := os.ReadFile(storagePath)
 	if err != nil {
 		if os.IsNotExist(err) {
-			return make(map[string]interface{}), nil
+			r.storageCache = make(map[string]interface{})
+			r.storageLoaded = true
+			return nil
 		}
-		return nil, err
+		return err
 	}
 
 	var storage map[string]interface{}
 	if err := json.Unmarshal(data, &storage); err != nil {
+		return err
+	}
+	if storage == nil {
+		storage = make(map[string]interface{})
+	}
+
+	r.storageCache = storage
+	r.storageLoaded = true
+	return nil
+}
+
+func (r *extensionRuntime) loadStorage() (map[string]interface{}, error) {
+	if err := r.ensureStorageLoaded(); err != nil {
 		return nil, err
 	}
 
-	return storage, nil
+	r.storageMu.RLock()
+	defer r.storageMu.RUnlock()
+	return cloneInterfaceMap(r.storageCache), nil
 }
 
-// saveStorage saves the storage data to disk
-func (r *ExtensionRuntime) saveStorage(storage map[string]interface{}) error {
-	storagePath := r.getStoragePath()
-	data, err := json.MarshalIndent(storage, "", "  ")
+func (r *extensionRuntime) queueStorageFlushLocked(delay time.Duration) {
+	if r.storageClosed {
+		return
+	}
+	if r.storageTimer != nil {
+		return
+	}
+	r.storageTimer = time.AfterFunc(delay, r.flushStorageDirtyAsync)
+}
+
+func (r *extensionRuntime) persistStorageSnapshot(storage map[string]interface{}) error {
+	data, err := json.Marshal(storage)
 	if err != nil {
 		return err
 	}
 
-	return os.WriteFile(storagePath, data, 0644)
+	r.storageWriteMu.Lock()
+	defer r.storageWriteMu.Unlock()
+
+	return os.WriteFile(r.getStoragePath(), data, 0600)
 }
 
-// storageGet retrieves a value from storage
-func (r *ExtensionRuntime) storageGet(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) flushStorageDirtyAsync() {
+	if err := r.flushStorageDirty(); err != nil {
+		GoLog("[Extension:%s] Storage flush error: %v\n", r.extensionID, err)
+	}
+}
+
+func (r *extensionRuntime) flushStorageDirty() error {
+	r.storageMu.Lock()
+	if r.storageClosed {
+		r.storageTimer = nil
+		r.storageMu.Unlock()
+		return nil
+	}
+	if !r.storageDirty {
+		r.storageTimer = nil
+		r.storageMu.Unlock()
+		return nil
+	}
+	snapshot := cloneInterfaceMap(r.storageCache)
+	r.storageDirty = false
+	r.storageTimer = nil
+	r.storageMu.Unlock()
+
+	if err := r.persistStorageSnapshot(snapshot); err != nil {
+		r.storageMu.Lock()
+		r.storageDirty = true
+		r.queueStorageFlushLocked(storageFlushRetryDelay)
+		r.storageMu.Unlock()
+		return err
+	}
+
+	return nil
+}
+
+func (r *extensionRuntime) flushStorageNow() error {
+	r.storageMu.Lock()
+	if r.storageTimer != nil {
+		r.storageTimer.Stop()
+		r.storageTimer = nil
+	}
+	if !r.storageLoaded || r.storageClosed {
+		r.storageMu.Unlock()
+		return nil
+	}
+	snapshot := cloneInterfaceMap(r.storageCache)
+	r.storageDirty = false
+	r.storageMu.Unlock()
+
+	return r.persistStorageSnapshot(snapshot)
+}
+
+func (r *extensionRuntime) closeStorageFlusher() {
+	r.storageMu.Lock()
+	r.storageClosed = true
+	r.storageDirty = false
+	if r.storageTimer != nil {
+		r.storageTimer.Stop()
+		r.storageTimer = nil
+	}
+	r.storageMu.Unlock()
+}
+
+func (r *extensionRuntime) storageGet(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return goja.Undefined()
 	}
 
 	key := call.Arguments[0].String()
 
-	storage, err := r.loadStorage()
-	if err != nil {
+	if err := r.ensureStorageLoaded(); err != nil {
 		GoLog("[Extension:%s] Storage load error: %v\n", r.extensionID, err)
 		return goja.Undefined()
 	}
 
-	value, exists := storage[key]
+	r.storageMu.RLock()
+	value, exists := r.storageCache[key]
+	r.storageMu.RUnlock()
 	if !exists {
-		// Return default value if provided
 		if len(call.Arguments) > 1 {
 			return call.Arguments[1]
 		}
@@ -78,8 +193,7 @@ func (r *ExtensionRuntime) storageGet(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(value)
 }
 
-// storageSet stores a value in storage
-func (r *ExtensionRuntime) storageSet(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) storageSet(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(false)
 	}
@@ -87,60 +201,68 @@ func (r *ExtensionRuntime) storageSet(call goja.FunctionCall) goja.Value {
 	key := call.Arguments[0].String()
 	value := call.Arguments[1].Export()
 
-	storage, err := r.loadStorage()
-	if err != nil {
+	if err := r.ensureStorageLoaded(); err != nil {
 		GoLog("[Extension:%s] Storage load error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(false)
 	}
 
-	storage[key] = value
-
-	if err := r.saveStorage(storage); err != nil {
-		GoLog("[Extension:%s] Storage save error: %v\n", r.extensionID, err)
+	r.storageMu.Lock()
+	if r.storageClosed {
+		r.storageMu.Unlock()
 		return r.vm.ToValue(false)
 	}
+	if existing, exists := r.storageCache[key]; exists {
+		if reflect.DeepEqual(existing, value) {
+			r.storageMu.Unlock()
+			return r.vm.ToValue(true)
+		}
+	}
+	r.storageCache[key] = value
+	r.storageDirty = true
+	r.queueStorageFlushLocked(r.storageFlushDelay)
+	r.storageMu.Unlock()
 
 	return r.vm.ToValue(true)
 }
 
-// storageRemove removes a value from storage
-func (r *ExtensionRuntime) storageRemove(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) storageRemove(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
 	}
 
 	key := call.Arguments[0].String()
 
-	storage, err := r.loadStorage()
-	if err != nil {
+	if err := r.ensureStorageLoaded(); err != nil {
 		GoLog("[Extension:%s] Storage load error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(false)
 	}
 
-	delete(storage, key)
-
-	if err := r.saveStorage(storage); err != nil {
-		GoLog("[Extension:%s] Storage save error: %v\n", r.extensionID, err)
+	r.storageMu.Lock()
+	if r.storageClosed {
+		r.storageMu.Unlock()
 		return r.vm.ToValue(false)
 	}
+	if _, exists := r.storageCache[key]; !exists {
+		r.storageMu.Unlock()
+		return r.vm.ToValue(true)
+	}
+	delete(r.storageCache, key)
+	r.storageDirty = true
+	r.queueStorageFlushLocked(r.storageFlushDelay)
+	r.storageMu.Unlock()
 
 	return r.vm.ToValue(true)
 }
 
-// ==================== Credentials API (Encrypted Storage) ====================
-
-// getCredentialsPath returns the path to the extension's encrypted credentials file
-func (r *ExtensionRuntime) getCredentialsPath() string {
+func (r *extensionRuntime) getCredentialsPath() string {
 	return filepath.Join(r.dataDir, ".credentials.enc")
 }
 
-// getSaltPath returns the path to the extension's encryption salt file
-func (r *ExtensionRuntime) getSaltPath() string {
+func (r *extensionRuntime) getSaltPath() string {
 	return filepath.Join(r.dataDir, ".cred_salt")
 }
 
-// getOrCreateSalt gets existing salt or creates a new random one
-func (r *ExtensionRuntime) getOrCreateSalt() ([]byte, error) {
+func (r *extensionRuntime) getOrCreateSalt() ([]byte, error) {
 	saltPath := r.getSaltPath()
 
 	salt, err := os.ReadFile(saltPath)
@@ -160,52 +282,75 @@ func (r *ExtensionRuntime) getOrCreateSalt() ([]byte, error) {
 	return salt, nil
 }
 
-// getEncryptionKey derives an encryption key from extension ID + random salt
-func (r *ExtensionRuntime) getEncryptionKey() ([]byte, error) {
-	// Get or create per-installation random salt
+func (r *extensionRuntime) getEncryptionKey() ([]byte, error) {
 	salt, err := r.getOrCreateSalt()
 	if err != nil {
 		return nil, err
 	}
 
-	// Combine extension ID + random salt for key derivation
-	// This makes each installation unique, preventing mass decryption attacks
 	combined := append([]byte(r.extensionID), salt...)
 	hash := sha256.Sum256(combined)
 	return hash[:], nil
 }
 
-// loadCredentials loads and decrypts credentials from disk
-func (r *ExtensionRuntime) loadCredentials() (map[string]interface{}, error) {
+func (r *extensionRuntime) ensureCredentialsLoaded() error {
+	r.credentialsMu.RLock()
+	if r.credentialsLoaded {
+		r.credentialsMu.RUnlock()
+		return nil
+	}
+	r.credentialsMu.RUnlock()
+
+	r.credentialsMu.Lock()
+	defer r.credentialsMu.Unlock()
+	if r.credentialsLoaded {
+		return nil
+	}
+
 	credPath := r.getCredentialsPath()
 	data, err := os.ReadFile(credPath)
 	if err != nil {
 		if os.IsNotExist(err) {
-			return make(map[string]interface{}), nil
+			r.credentialsCache = make(map[string]interface{})
+			r.credentialsLoaded = true
+			return nil
 		}
-		return nil, err
+		return err
 	}
 
-	// Decrypt the data
 	key, err := r.getEncryptionKey()
 	if err != nil {
-		return nil, fmt.Errorf("failed to get encryption key: %w", err)
+		return fmt.Errorf("failed to get encryption key: %w", err)
 	}
 	decrypted, err := decryptAES(data, key)
 	if err != nil {
-		return nil, fmt.Errorf("failed to decrypt credentials: %w", err)
+		return fmt.Errorf("failed to decrypt credentials: %w", err)
 	}
 
 	var creds map[string]interface{}
 	if err := json.Unmarshal(decrypted, &creds); err != nil {
+		return err
+	}
+	if creds == nil {
+		creds = make(map[string]interface{})
+	}
+
+	r.credentialsCache = creds
+	r.credentialsLoaded = true
+	return nil
+}
+
+func (r *extensionRuntime) loadCredentials() (map[string]interface{}, error) {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		return nil, err
 	}
 
-	return creds, nil
+	r.credentialsMu.RLock()
+	defer r.credentialsMu.RUnlock()
+	return cloneInterfaceMap(r.credentialsCache), nil
 }
 
-// saveCredentials encrypts and saves credentials to disk
-func (r *ExtensionRuntime) saveCredentials(creds map[string]interface{}) error {
+func (r *extensionRuntime) saveCredentials(creds map[string]interface{}) error {
 	data, err := json.Marshal(creds)
 	if err != nil {
 		return err
@@ -221,11 +366,18 @@ func (r *ExtensionRuntime) saveCredentials(creds map[string]interface{}) error {
 	}
 
 	credPath := r.getCredentialsPath()
-	return os.WriteFile(credPath, encrypted, 0600) // Restrictive permissions
+	if err := os.WriteFile(credPath, encrypted, 0600); err != nil {
+		return err
+	}
+
+	r.credentialsMu.Lock()
+	r.credentialsCache = cloneInterfaceMap(creds)
+	r.credentialsLoaded = true
+	r.credentialsMu.Unlock()
+	return nil
 }
 
-// credentialsStore stores an encrypted credential
-func (r *ExtensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -236,8 +388,7 @@ func (r *ExtensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
 	key := call.Arguments[0].String()
 	value := call.Arguments[1].Export()
 
-	creds, err := r.loadCredentials()
-	if err != nil {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		GoLog("[Extension:%s] Credentials load error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -245,9 +396,12 @@ func (r *ExtensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	creds[key] = value
+	r.credentialsMu.RLock()
+	nextCreds := cloneInterfaceMap(r.credentialsCache)
+	r.credentialsMu.RUnlock()
+	nextCreds[key] = value
 
-	if err := r.saveCredentials(creds); err != nil {
+	if err := r.saveCredentials(nextCreds); err != nil {
 		GoLog("[Extension:%s] Credentials save error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -260,23 +414,22 @@ func (r *ExtensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
 	})
 }
 
-// credentialsGet retrieves a decrypted credential
-func (r *ExtensionRuntime) credentialsGet(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) credentialsGet(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return goja.Undefined()
 	}
 
 	key := call.Arguments[0].String()
 
-	creds, err := r.loadCredentials()
-	if err != nil {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		GoLog("[Extension:%s] Credentials load error: %v\n", r.extensionID, err)
 		return goja.Undefined()
 	}
 
-	value, exists := creds[key]
+	r.credentialsMu.RLock()
+	value, exists := r.credentialsCache[key]
+	r.credentialsMu.RUnlock()
 	if !exists {
-		// Return default value if provided
 		if len(call.Arguments) > 1 {
 			return call.Arguments[1]
 		}
@@ -286,23 +439,24 @@ func (r *ExtensionRuntime) credentialsGet(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(value)
 }
 
-// credentialsRemove removes a credential
-func (r *ExtensionRuntime) credentialsRemove(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) credentialsRemove(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
 	}
 
 	key := call.Arguments[0].String()
 
-	creds, err := r.loadCredentials()
-	if err != nil {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		GoLog("[Extension:%s] Credentials load error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(false)
 	}
 
-	delete(creds, key)
+	r.credentialsMu.RLock()
+	nextCreds := cloneInterfaceMap(r.credentialsCache)
+	r.credentialsMu.RUnlock()
+	delete(nextCreds, key)
 
-	if err := r.saveCredentials(creds); err != nil {
+	if err := r.saveCredentials(nextCreds); err != nil {
 		GoLog("[Extension:%s] Credentials save error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(false)
 	}
@@ -310,26 +464,23 @@ func (r *ExtensionRuntime) credentialsRemove(call goja.FunctionCall) goja.Value
 	return r.vm.ToValue(true)
 }
 
-// credentialsHas checks if a credential exists
-func (r *ExtensionRuntime) credentialsHas(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) credentialsHas(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
 	}
 
 	key := call.Arguments[0].String()
 
-	creds, err := r.loadCredentials()
-	if err != nil {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		return r.vm.ToValue(false)
 	}
 
-	_, exists := creds[key]
+	r.credentialsMu.RLock()
+	_, exists := r.credentialsCache[key]
+	r.credentialsMu.RUnlock()
 	return r.vm.ToValue(exists)
 }
 
-// ==================== Crypto Utilities ====================
-
-// encryptAES encrypts data using AES-GCM
 func encryptAES(plaintext []byte, key []byte) ([]byte, error) {
 	block, err := aes.NewCipher(key)
 	if err != nil {
@@ -350,7 +501,6 @@ func encryptAES(plaintext []byte, key []byte) ([]byte, error) {
 	return ciphertext, nil
 }
 
-// decryptAES decrypts data using AES-GCM
 func decryptAES(ciphertext []byte, key []byte) ([]byte, error) {
 	block, err := aes.NewCipher(key)
 	if err != nil {

go_backend/extension_runtime_storage_test.go

@@ -0,0 +1,120 @@
+package gobackend
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/dop251/goja"
+)
+
+func setStorageValue(t *testing.T, runtime *extensionRuntime, key string, value interface{}) {
+	t.Helper()
+	result := runtime.storageSet(goja.FunctionCall{
+		Arguments: []goja.Value{
+			runtime.vm.ToValue(key),
+			runtime.vm.ToValue(value),
+		},
+	})
+	if !result.ToBoolean() {
+		t.Fatalf("storage.set(%q) returned false", key)
+	}
+}
+
+func readStorageMap(t *testing.T, storagePath string) map[string]interface{} {
+	t.Helper()
+	data, err := os.ReadFile(storagePath)
+	if err != nil {
+		t.Fatalf("failed to read storage file: %v", err)
+	}
+
+	var parsed map[string]interface{}
+	if err := json.Unmarshal(data, &parsed); err != nil {
+		t.Fatalf("failed to unmarshal storage file: %v", err)
+	}
+	return parsed
+}
+
+func TestExtensionRuntimeStorage_DebouncedWriteCompactJSON(t *testing.T) {
+	ext := &loadedExtension{
+		ID: "storage-test",
+		Manifest: &ExtensionManifest{
+			Name: "storage-test",
+		},
+		DataDir: t.TempDir(),
+	}
+
+	runtime := newExtensionRuntime(ext)
+	runtime.storageFlushDelay = 25 * time.Millisecond
+	runtime.RegisterAPIs(goja.New())
+
+	setStorageValue(t, runtime, "k1", "v1")
+	setStorageValue(t, runtime, "k2", 2)
+
+	storagePath := filepath.Join(ext.DataDir, "storage.json")
+	deadline := time.Now().Add(1500 * time.Millisecond)
+
+	var raw []byte
+	for time.Now().Before(deadline) {
+		data, err := os.ReadFile(storagePath)
+		if err == nil {
+			raw = data
+			break
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	if len(raw) == 0 {
+		t.Fatalf("storage.json was not written within timeout")
+	}
+
+	var parsed map[string]interface{}
+	if err := json.Unmarshal(raw, &parsed); err != nil {
+		t.Fatalf("failed to unmarshal storage file: %v", err)
+	}
+	if parsed["k1"] != "v1" {
+		t.Fatalf("expected k1=v1, got %v", parsed["k1"])
+	}
+	if parsed["k2"] != float64(2) {
+		t.Fatalf("expected k2=2, got %v", parsed["k2"])
+	}
+	if bytes.Contains(raw, []byte("\n")) {
+		t.Fatalf("expected compact JSON without indentation, got: %q", string(raw))
+	}
+}
+
+func TestUnloadExtension_FlushesPendingStorage(t *testing.T) {
+	ext := &loadedExtension{
+		ID: "unload-storage-test",
+		Manifest: &ExtensionManifest{
+			Name: "unload-storage-test",
+		},
+		DataDir: t.TempDir(),
+		VM:      goja.New(),
+	}
+
+	runtime := newExtensionRuntime(ext)
+	runtime.storageFlushDelay = time.Hour
+	runtime.RegisterAPIs(ext.VM)
+	ext.runtime = runtime
+
+	manager := &extensionManager{
+		extensions: map[string]*loadedExtension{
+			ext.ID: ext,
+		},
+	}
+
+	setStorageValue(t, runtime, "persist_on_unload", true)
+
+	if err := manager.UnloadExtension(ext.ID); err != nil {
+		t.Fatalf("UnloadExtension failed: %v", err)
+	}
+
+	storagePath := filepath.Join(ext.DataDir, "storage.json")
+	parsed := readStorageMap(t, storagePath)
+	if parsed["persist_on_unload"] != true {
+		t.Fatalf("expected pending storage value to be flushed on unload, got %v", parsed["persist_on_unload"])
+	}
+}

go_backend/extension_runtime_utils.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Utility functions for extension runtime
 package gobackend
 
 import (
@@ -17,10 +16,7 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== Utility Functions ====================
-
-// base64Encode encodes a string to base64
-func (r *ExtensionRuntime) base64Encode(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) base64Encode(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -28,8 +24,7 @@ func (r *ExtensionRuntime) base64Encode(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(base64.StdEncoding.EncodeToString([]byte(input)))
 }
 
-// base64Decode decodes a base64 string
-func (r *ExtensionRuntime) base64Decode(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) base64Decode(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -41,8 +36,7 @@ func (r *ExtensionRuntime) base64Decode(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(string(decoded))
 }
 
-// md5Hash computes MD5 hash of a string
-func (r *ExtensionRuntime) md5Hash(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) md5Hash(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -51,8 +45,7 @@ func (r *ExtensionRuntime) md5Hash(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(hex.EncodeToString(hash[:]))
 }
 
-// sha256Hash computes SHA256 hash of a string
-func (r *ExtensionRuntime) sha256Hash(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) sha256Hash(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -61,8 +54,7 @@ func (r *ExtensionRuntime) sha256Hash(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(hex.EncodeToString(hash[:]))
 }
 
-// hmacSHA256 computes HMAC-SHA256 of a message with a key
-func (r *ExtensionRuntime) hmacSHA256(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) hmacSHA256(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue("")
 	}
@@ -74,8 +66,7 @@ func (r *ExtensionRuntime) hmacSHA256(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(hex.EncodeToString(mac.Sum(nil)))
 }
 
-// hmacSHA256Base64 computes HMAC-SHA256 and returns base64 encoded result
-func (r *ExtensionRuntime) hmacSHA256Base64(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) hmacSHA256Base64(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue("")
 	}
@@ -87,10 +78,7 @@ func (r *ExtensionRuntime) hmacSHA256Base64(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(base64.StdEncoding.EncodeToString(mac.Sum(nil)))
 }
 
-// hmacSHA1 computes HMAC-SHA1 of a message with a key (for TOTP)
-// Arguments: message (string or array of bytes), key (string or array of bytes)
-// Returns: array of bytes (for TOTP dynamic truncation)
-func (r *ExtensionRuntime) hmacSHA1(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) hmacSHA1(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue([]byte{})
 	}
@@ -142,8 +130,7 @@ func (r *ExtensionRuntime) hmacSHA1(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(jsArray)
 }
 
-// parseJSON parses a JSON string
-func (r *ExtensionRuntime) parseJSON(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) parseJSON(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return goja.Undefined()
 	}
@@ -158,8 +145,7 @@ func (r *ExtensionRuntime) parseJSON(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(result)
 }
 
-// stringifyJSON converts a value to JSON string
-func (r *ExtensionRuntime) stringifyJSON(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) stringifyJSON(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -174,10 +160,7 @@ func (r *ExtensionRuntime) stringifyJSON(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(string(data))
 }
 
-// ==================== Crypto Utilities for Extensions ====================
-
-// cryptoEncrypt encrypts a string using AES-GCM (for extension use)
-func (r *ExtensionRuntime) cryptoEncrypt(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) cryptoEncrypt(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -188,7 +171,6 @@ func (r *ExtensionRuntime) cryptoEncrypt(call goja.FunctionCall) goja.Value {
 	plaintext := call.Arguments[0].String()
 	keyStr := call.Arguments[1].String()
 
-	// Derive 32-byte key from provided key string
 	keyHash := sha256.Sum256([]byte(keyStr))
 
 	encrypted, err := encryptAES([]byte(plaintext), keyHash[:])
@@ -205,8 +187,7 @@ func (r *ExtensionRuntime) cryptoEncrypt(call goja.FunctionCall) goja.Value {
 	})
 }
 
-// cryptoDecrypt decrypts a string using AES-GCM (for extension use)
-func (r *ExtensionRuntime) cryptoDecrypt(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) cryptoDecrypt(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -225,14 +206,13 @@ func (r *ExtensionRuntime) cryptoDecrypt(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	// Derive 32-byte key from provided key string
 	keyHash := sha256.Sum256([]byte(keyStr))
 
 	decrypted, err := decryptAES(ciphertext, keyHash[:])
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
-			"error":   err.Error(),
+			"error":   "invalid base64 ciphertext",
 		})
 	}
 
@@ -242,9 +222,8 @@ func (r *ExtensionRuntime) cryptoDecrypt(call goja.FunctionCall) goja.Value {
 	})
 }
 
-// cryptoGenerateKey generates a random encryption key
-func (r *ExtensionRuntime) cryptoGenerateKey(call goja.FunctionCall) goja.Value {
-	length := 32 // Default 256-bit key
+func (r *extensionRuntime) cryptoGenerateKey(call goja.FunctionCall) goja.Value {
+	length := 32
 	if len(call.Arguments) > 0 && !goja.IsUndefined(call.Arguments[0]) {
 		if l, ok := call.Arguments[0].Export().(float64); ok {
 			length = int(l)
@@ -266,38 +245,35 @@ func (r *ExtensionRuntime) cryptoGenerateKey(call goja.FunctionCall) goja.Value
 	})
 }
 
-// randomUserAgent returns a random Chrome User-Agent string
-func (r *ExtensionRuntime) randomUserAgent(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) randomUserAgent(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(getRandomUserAgent())
 }
 
-// ==================== Logging Functions ====================
-
-func (r *ExtensionRuntime) logDebug(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) logDebug(call goja.FunctionCall) goja.Value {
 	msg := r.formatLogArgs(call.Arguments)
 	GoLog("[Extension:%s:DEBUG] %s\n", r.extensionID, msg)
 	return goja.Undefined()
 }
 
-func (r *ExtensionRuntime) logInfo(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) logInfo(call goja.FunctionCall) goja.Value {
 	msg := r.formatLogArgs(call.Arguments)
 	GoLog("[Extension:%s:INFO] %s\n", r.extensionID, msg)
 	return goja.Undefined()
 }
 
-func (r *ExtensionRuntime) logWarn(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) logWarn(call goja.FunctionCall) goja.Value {
 	msg := r.formatLogArgs(call.Arguments)
 	GoLog("[Extension:%s:WARN] %s\n", r.extensionID, msg)
 	return goja.Undefined()
 }
 
-func (r *ExtensionRuntime) logError(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) logError(call goja.FunctionCall) goja.Value {
 	msg := r.formatLogArgs(call.Arguments)
 	GoLog("[Extension:%s:ERROR] %s\n", r.extensionID, msg)
 	return goja.Undefined()
 }
 
-func (r *ExtensionRuntime) formatLogArgs(args []goja.Value) string {
+func (r *extensionRuntime) formatLogArgs(args []goja.Value) string {
 	parts := make([]string, len(args))
 	for i, arg := range args {
 		parts[i] = fmt.Sprintf("%v", arg.Export())
@@ -305,9 +281,7 @@ func (r *ExtensionRuntime) formatLogArgs(args []goja.Value) string {
 	return strings.Join(parts, " ")
 }
 
-// ==================== Go Backend Wrappers ====================
-
-func (r *ExtensionRuntime) sanitizeFilenameWrapper(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) sanitizeFilenameWrapper(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -315,8 +289,7 @@ func (r *ExtensionRuntime) sanitizeFilenameWrapper(call goja.FunctionCall) goja.
 	return r.vm.ToValue(sanitizeFilename(input))
 }
 
-// RegisterGoBackendAPIs adds more Go backend functions to the VM
-func (r *ExtensionRuntime) RegisterGoBackendAPIs(vm *goja.Runtime) {
+func (r *extensionRuntime) RegisterGoBackendAPIs(vm *goja.Runtime) {
 	gobackendObj := vm.Get("gobackend")
 	if gobackendObj == nil || goja.IsUndefined(gobackendObj) {
 		gobackendObj = vm.NewObject()
@@ -325,7 +298,6 @@ func (r *ExtensionRuntime) RegisterGoBackendAPIs(vm *goja.Runtime) {
 
 	obj := gobackendObj.(*goja.Object)
 
-	// Expose sanitizeFilename
 	obj.Set("sanitizeFilename", func(call goja.FunctionCall) goja.Value {
 		if len(call.Arguments) < 1 {
 			return vm.ToValue("")
@@ -333,7 +305,6 @@ func (r *ExtensionRuntime) RegisterGoBackendAPIs(vm *goja.Runtime) {
 		return vm.ToValue(sanitizeFilename(call.Arguments[0].String()))
 	})
 
-	// Expose getAudioQuality
 	obj.Set("getAudioQuality", func(call goja.FunctionCall) goja.Value {
 		if len(call.Arguments) < 1 {
 			return vm.ToValue(map[string]interface{}{
@@ -356,7 +327,6 @@ func (r *ExtensionRuntime) RegisterGoBackendAPIs(vm *goja.Runtime) {
 		})
 	})
 
-	// Expose buildFilename
 	obj.Set("buildFilename", func(call goja.FunctionCall) goja.Value {
 		if len(call.Arguments) < 2 {
 			return vm.ToValue("")
@@ -373,7 +343,6 @@ func (r *ExtensionRuntime) RegisterGoBackendAPIs(vm *goja.Runtime) {
 		return vm.ToValue(buildFilenameFromTemplate(template, metadata))
 	})
 
-	// Expose getLocalTime - returns device local time info
 	obj.Set("getLocalTime", func(call goja.FunctionCall) goja.Value {
 		now := time.Now()
 		_, offsetSeconds := now.Zone()

go_backend/extension_settings.go

@@ -1,4 +1,3 @@
-// Package gobackend provides extension settings storage
 package gobackend
 
 import (
@@ -9,20 +8,17 @@ import (
 	"sync"
 )
 
-// ExtensionSettingsStore manages settings for all extensions
 type ExtensionSettingsStore struct {
 	mu       sync.RWMutex
 	dataDir  string
 	settings map[string]map[string]interface{} // extensionID -> settings
 }
 
-// Global settings store
 var (
 	globalSettingsStore     *ExtensionSettingsStore
 	globalSettingsStoreOnce sync.Once
 )
 
-// GetExtensionSettingsStore returns the global settings store
 func GetExtensionSettingsStore() *ExtensionSettingsStore {
 	globalSettingsStoreOnce.Do(func() {
 		globalSettingsStore = &ExtensionSettingsStore{
@@ -32,7 +28,6 @@ func GetExtensionSettingsStore() *ExtensionSettingsStore {
 	return globalSettingsStore
 }
 
-// SetDataDir sets the data directory for settings storage
 func (s *ExtensionSettingsStore) SetDataDir(dataDir string) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -45,12 +40,10 @@ func (s *ExtensionSettingsStore) SetDataDir(dataDir string) error {
 	return s.loadAllSettings()
 }
 
-// getSettingsPath returns the path to an extension's settings file
 func (s *ExtensionSettingsStore) getSettingsPath(extensionID string) string {
 	return filepath.Join(s.dataDir, extensionID, "settings.json")
 }
 
-// loadAllSettings loads settings for all extensions from disk
 func (s *ExtensionSettingsStore) loadAllSettings() error {
 	entries, err := os.ReadDir(s.dataDir)
 	if err != nil {
@@ -75,7 +68,6 @@ func (s *ExtensionSettingsStore) loadAllSettings() error {
 	return nil
 }
 
-// loadSettings loads settings for a specific extension
 func (s *ExtensionSettingsStore) loadSettings(extensionID string) (map[string]interface{}, error) {
 	settingsPath := s.getSettingsPath(extensionID)
 	data, err := os.ReadFile(settingsPath)
@@ -94,7 +86,6 @@ func (s *ExtensionSettingsStore) loadSettings(extensionID string) (map[string]in
 	return settings, nil
 }
 
-// saveSettings saves settings for a specific extension
 func (s *ExtensionSettingsStore) saveSettings(extensionID string, settings map[string]interface{}) error {
 	settingsPath := s.getSettingsPath(extensionID)
 
@@ -111,8 +102,6 @@ func (s *ExtensionSettingsStore) saveSettings(extensionID string, settings map[s
 	return os.WriteFile(settingsPath, data, 0644)
 }
 
-// Get retrieves a setting value for an extension
-// Returns error if extension or key not found (gomobile compatible)
 func (s *ExtensionSettingsStore) Get(extensionID, key string) (interface{}, error) {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
@@ -129,7 +118,6 @@ func (s *ExtensionSettingsStore) Get(extensionID, key string) (interface{}, erro
 	return value, nil
 }
 
-// GetAll retrieves all settings for an extension
 func (s *ExtensionSettingsStore) GetAll(extensionID string) map[string]interface{} {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
@@ -139,7 +127,6 @@ func (s *ExtensionSettingsStore) GetAll(extensionID string) map[string]interface
 		return make(map[string]interface{})
 	}
 
-	// Return a copy
 	result := make(map[string]interface{})
 	for k, v := range extSettings {
 		result[k] = v
@@ -147,7 +134,6 @@ func (s *ExtensionSettingsStore) GetAll(extensionID string) map[string]interface
 	return result
 }
 
-// Set stores a setting value for an extension
 func (s *ExtensionSettingsStore) Set(extensionID, key string, value interface{}) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -161,18 +147,15 @@ func (s *ExtensionSettingsStore) Set(extensionID, key string, value interface{})
 	return s.saveSettings(extensionID, s.settings[extensionID])
 }
 
-// SetAll stores all settings for an extension
 func (s *ExtensionSettingsStore) SetAll(extensionID string, settings map[string]interface{}) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 
 	s.settings[extensionID] = settings
 
-	// Persist to disk
 	return s.saveSettings(extensionID, settings)
 }
 
-// Remove removes a setting for an extension
 func (s *ExtensionSettingsStore) Remove(extensionID, key string) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -184,11 +167,9 @@ func (s *ExtensionSettingsStore) Remove(extensionID, key string) error {
 
 	delete(extSettings, key)
 
-	// Persist to disk
 	return s.saveSettings(extensionID, extSettings)
 }
 
-// RemoveAll removes all settings for an extension
 func (s *ExtensionSettingsStore) RemoveAll(extensionID string) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -203,7 +184,6 @@ func (s *ExtensionSettingsStore) RemoveAll(extensionID string) error {
 	return nil
 }
 
-// GetAllExtensionSettings returns settings for all extensions as JSON
 func (s *ExtensionSettingsStore) GetAllExtensionSettingsJSON() (string, error) {
 	s.mu.RLock()
 	defer s.mu.RUnlock()

go_backend/extension_store.go

@@ -5,13 +5,14 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"net/url"
 	"os"
 	"path/filepath"
+	"strings"
 	"sync"
 	"time"
 )
 
-// Extension categories
 const (
 	CategoryMetadata    = "metadata"
 	CategoryDownload    = "download"
@@ -20,29 +21,27 @@ const (
 	CategoryIntegration = "integration"
 )
 
-// StoreExtension represents an extension in the store
-type StoreExtension struct {
-	ID            string   `json:"id"`
-	Name          string   `json:"name"`
-	DisplayName   string   `json:"display_name,omitempty"`
-	Version       string   `json:"version"`
-	Author        string   `json:"author"`
-	Description   string   `json:"description"`
-	DownloadURL   string   `json:"download_url,omitempty"`
-	IconURL       string   `json:"icon_url,omitempty"`
-	Category      string   `json:"category"`
-	Tags          []string `json:"tags,omitempty"`
-	Downloads     int      `json:"downloads"`
-	UpdatedAt     string   `json:"updated_at"`
-	MinAppVersion string   `json:"min_app_version,omitempty"`
-	DisplayNameAlt   string `json:"displayName,omitempty"`
-	DownloadURLAlt   string `json:"downloadUrl,omitempty"`
-	IconURLAlt       string `json:"iconUrl,omitempty"`
-	MinAppVersionAlt string `json:"minAppVersion,omitempty"`
+type storeExtension struct {
+	ID               string   `json:"id"`
+	Name             string   `json:"name"`
+	DisplayName      string   `json:"display_name,omitempty"`
+	Version          string   `json:"version"`
+	Author           string   `json:"author"`
+	Description      string   `json:"description"`
+	DownloadURL      string   `json:"download_url,omitempty"`
+	IconURL          string   `json:"icon_url,omitempty"`
+	Category         string   `json:"category"`
+	Tags             []string `json:"tags,omitempty"`
+	Downloads        int      `json:"downloads"`
+	UpdatedAt        string   `json:"updated_at"`
+	MinAppVersion    string   `json:"min_app_version,omitempty"`
+	DisplayNameAlt   string   `json:"displayName,omitempty"`
+	DownloadURLAlt   string   `json:"downloadUrl,omitempty"`
+	IconURLAlt       string   `json:"iconUrl,omitempty"`
+	MinAppVersionAlt string   `json:"minAppVersion,omitempty"`
 }
 
-// getDisplayName returns display name, falling back to name (private to avoid gomobile conflict)
-func (e *StoreExtension) getDisplayName() string {
+func (e *storeExtension) getDisplayName() string {
 	if e.DisplayName != "" {
 		return e.DisplayName
 	}
@@ -52,39 +51,34 @@ func (e *StoreExtension) getDisplayName() string {
 	return e.Name
 }
 
-// getDownloadURL returns download URL from either field (private to avoid gomobile conflict)
-func (e *StoreExtension) getDownloadURL() string {
+func (e *storeExtension) getDownloadURL() string {
 	if e.DownloadURL != "" {
 		return e.DownloadURL
 	}
 	return e.DownloadURLAlt
 }
 
-// getIconURL returns icon URL from either field (private to avoid gomobile conflict)
-func (e *StoreExtension) getIconURL() string {
+func (e *storeExtension) getIconURL() string {
 	if e.IconURL != "" {
 		return e.IconURL
 	}
 	return e.IconURLAlt
 }
 
-// getMinAppVersion returns min app version from either field (private to avoid gomobile conflict)
-func (e *StoreExtension) getMinAppVersion() string {
+func (e *storeExtension) getMinAppVersion() string {
 	if e.MinAppVersion != "" {
 		return e.MinAppVersion
 	}
 	return e.MinAppVersionAlt
 }
 
-// StoreRegistry represents the extension registry
-type StoreRegistry struct {
+type storeRegistry struct {
 	Version    int              `json:"version"`
 	UpdatedAt  string           `json:"updated_at"`
-	Extensions []StoreExtension `json:"extensions"`
+	Extensions []storeExtension `json:"extensions"`
 }
 
-// StoreExtensionResponse is the normalized response sent to Flutter
-type StoreExtensionResponse struct {
+type storeExtensionResponse struct {
 	ID               string   `json:"id"`
 	Name             string   `json:"name"`
 	DisplayName      string   `json:"display_name"`
@@ -103,9 +97,8 @@ type StoreExtensionResponse struct {
 	HasUpdate        bool     `json:"has_update"`
 }
 
-// ToResponse converts StoreExtension to normalized response
-func (e *StoreExtension) ToResponse() StoreExtensionResponse {
-	return StoreExtensionResponse{
+func (e *storeExtension) toResponse() storeExtensionResponse {
+	resp := storeExtensionResponse{
 		ID:            e.ID,
 		Name:          e.Name,
 		DisplayName:   e.getDisplayName(),
@@ -115,60 +108,85 @@ func (e *StoreExtension) ToResponse() StoreExtensionResponse {
 		DownloadURL:   e.getDownloadURL(),
 		IconURL:       e.getIconURL(),
 		Category:      e.Category,
-		Tags:          e.Tags,
 		Downloads:     e.Downloads,
 		UpdatedAt:     e.UpdatedAt,
 		MinAppVersion: e.getMinAppVersion(),
 	}
+
+	if len(e.Tags) > 0 {
+		resp.Tags = append([]string(nil), e.Tags...)
+	}
+
+	return resp
 }
 
-// ExtensionStore manages the extension store
-type ExtensionStore struct {
+type extensionStore struct {
 	registryURL string
 	cacheDir    string
-	cache       *StoreRegistry
+	cache       *storeRegistry
 	cacheMu     sync.RWMutex
 	cacheTime   time.Time
 	cacheTTL    time.Duration
 }
 
 var (
-	extensionStore   *ExtensionStore
-	extensionStoreMu sync.Mutex
+	globalExtensionStore *extensionStore
+	extensionStoreMu     sync.Mutex
 )
 
 const (
-	defaultRegistryURL = "https://raw.githubusercontent.com/zarzet/SpotiFLAC-Extension/main/registry.json"
-	cacheTTL           = 30 * time.Minute
-	cacheFileName      = "store_cache.json"
+	cacheTTL      = 30 * time.Minute
+	cacheFileName = "store_cache.json"
 )
 
-// InitExtensionStore initializes the extension store
-func InitExtensionStore(cacheDir string) *ExtensionStore {
+func initExtensionStore(cacheDir string) *extensionStore {
 	extensionStoreMu.Lock()
 	defer extensionStoreMu.Unlock()
 
-	if extensionStore == nil {
-		extensionStore = &ExtensionStore{
-			registryURL: defaultRegistryURL,
+	if globalExtensionStore == nil {
+		globalExtensionStore = &extensionStore{
+			registryURL: "",
 			cacheDir:    cacheDir,
 			cacheTTL:    cacheTTL,
 		}
-		// Try to load from disk cache
-		extensionStore.loadDiskCache()
+		globalExtensionStore.loadDiskCache()
 	}
-	return extensionStore
+	return globalExtensionStore
 }
 
-// GetExtensionStore returns the singleton store instance
-func GetExtensionStore() *ExtensionStore {
+func (s *extensionStore) setRegistryURL(registryURL string) {
+	s.cacheMu.Lock()
+	defer s.cacheMu.Unlock()
+
+	if s.registryURL == registryURL {
+		return
+	}
+
+	s.registryURL = registryURL
+	s.cache = nil
+	s.cacheTime = time.Time{}
+
+	if s.cacheDir != "" {
+		cachePath := filepath.Join(s.cacheDir, cacheFileName)
+		os.Remove(cachePath)
+	}
+
+	LogInfo("ExtensionStore", "Registry URL updated to: %s", registryURL)
+}
+
+func (s *extensionStore) getRegistryURL() string {
+	s.cacheMu.RLock()
+	defer s.cacheMu.RUnlock()
+	return s.registryURL
+}
+
+func getExtensionStore() *extensionStore {
 	extensionStoreMu.Lock()
 	defer extensionStoreMu.Unlock()
-	return extensionStore
+	return globalExtensionStore
 }
 
-// loadDiskCache loads cached registry from disk
-func (s *ExtensionStore) loadDiskCache() {
+func (s *extensionStore) loadDiskCache() {
 	if s.cacheDir == "" {
 		return
 	}
@@ -180,7 +198,7 @@ func (s *ExtensionStore) loadDiskCache() {
 	}
 
 	var cacheData struct {
-		Registry  StoreRegistry `json:"registry"`
+		Registry  storeRegistry `json:"registry"`
 		CacheTime int64         `json:"cache_time"`
 	}
 
@@ -193,14 +211,13 @@ func (s *ExtensionStore) loadDiskCache() {
 	LogDebug("ExtensionStore", "Loaded %d extensions from disk cache", len(s.cache.Extensions))
 }
 
-// saveDiskCache saves registry to disk cache
-func (s *ExtensionStore) saveDiskCache() {
+func (s *extensionStore) saveDiskCache() {
 	if s.cacheDir == "" || s.cache == nil {
 		return
 	}
 
 	cacheData := struct {
-		Registry  StoreRegistry `json:"registry"`
+		Registry  storeRegistry `json:"registry"`
 		CacheTime int64         `json:"cache_time"`
 	}{
 		Registry:  *s.cache,
@@ -216,23 +233,28 @@ func (s *ExtensionStore) saveDiskCache() {
 	os.WriteFile(cachePath, data, 0644)
 }
 
-// FetchRegistry fetches the extension registry from GitHub
-func (s *ExtensionStore) FetchRegistry(forceRefresh bool) (*StoreRegistry, error) {
+func (s *extensionStore) fetchRegistry(forceRefresh bool) (*storeRegistry, error) {
 	s.cacheMu.Lock()
 	defer s.cacheMu.Unlock()
 
-	// Return cached if valid and not forcing refresh
+	if s.registryURL == "" {
+		return nil, fmt.Errorf("no registry URL configured. Please add a repository URL first")
+	}
+
 	if !forceRefresh && s.cache != nil && time.Since(s.cacheTime) < s.cacheTTL {
 		LogDebug("ExtensionStore", "Using cached registry (%d extensions)", len(s.cache.Extensions))
 		return s.cache, nil
 	}
 
+	if err := requireHTTPSURL(s.registryURL, "registry"); err != nil {
+		return nil, err
+	}
+
 	LogInfo("ExtensionStore", "Fetching registry from %s", s.registryURL)
 
-	client := &http.Client{Timeout: 30 * time.Second}
+	client := NewHTTPClientWithTimeout(30 * time.Second)
 	resp, err := client.Get(s.registryURL)
 	if err != nil {
-		// Return cached data if available on network error
 		if s.cache != nil {
 			LogWarn("ExtensionStore", "Network error, using cached registry: %v", err)
 			return s.cache, nil
@@ -254,7 +276,7 @@ func (s *ExtensionStore) FetchRegistry(forceRefresh bool) (*StoreRegistry, error
 		return nil, fmt.Errorf("failed to read registry: %w", err)
 	}
 
-	var registry StoreRegistry
+	var registry storeRegistry
 	if err := json.Unmarshal(body, &registry); err != nil {
 		return nil, fmt.Errorf("failed to parse registry: %w", err)
 	}
@@ -267,14 +289,13 @@ func (s *ExtensionStore) FetchRegistry(forceRefresh bool) (*StoreRegistry, error
 	return &registry, nil
 }
 
-// GetExtensionsWithStatus returns extensions with installation status
-func (s *ExtensionStore) GetExtensionsWithStatus() ([]StoreExtensionResponse, error) {
-	registry, err := s.FetchRegistry(false)
+func (s *extensionStore) getExtensionsWithStatus(forceRefresh bool) ([]storeExtensionResponse, error) {
+	registry, err := s.fetchRegistry(forceRefresh)
 	if err != nil {
 		return nil, err
 	}
 
-	manager := GetExtensionManager()
+	manager := getExtensionManager()
 	installed := make(map[string]string) // id -> version
 
 	if manager != nil {
@@ -283,30 +304,32 @@ func (s *ExtensionStore) GetExtensionsWithStatus() ([]StoreExtensionResponse, er
 		}
 	}
 
-	result := make([]StoreExtensionResponse, len(registry.Extensions))
-	for i, ext := range registry.Extensions {
-		resp := ext.ToResponse()
+	LogDebug("ExtensionStore", "Building store response for %d registry extensions (%d installed)", len(registry.Extensions), len(installed))
 
+	result := make([]storeExtensionResponse, 0, len(registry.Extensions))
+	for i := range registry.Extensions {
+		ext := &registry.Extensions[i]
+		resp := ext.toResponse()
 		if installedVersion, ok := installed[ext.ID]; ok {
 			resp.IsInstalled = true
 			resp.InstalledVersion = installedVersion
 			resp.HasUpdate = compareVersions(ext.Version, installedVersion) > 0
 		}
 
-		result[i] = resp
+		result = append(result, resp)
 	}
 
+	LogDebug("ExtensionStore", "Built store response payload for %d extensions", len(result))
 	return result, nil
 }
 
-// DownloadExtension downloads an extension package to the specified path
-func (s *ExtensionStore) DownloadExtension(extensionID string, destPath string) error {
-	registry, err := s.FetchRegistry(false)
+func (s *extensionStore) downloadExtension(extensionID string, destPath string) error {
+	registry, err := s.fetchRegistry(false)
 	if err != nil {
 		return err
 	}
 
-	var ext *StoreExtension
+	var ext *storeExtension
 	for _, e := range registry.Extensions {
 		if e.ID == extensionID {
 			ext = &e
@@ -318,9 +341,13 @@ func (s *ExtensionStore) DownloadExtension(extensionID string, destPath string)
 		return fmt.Errorf("extension %s not found in store", extensionID)
 	}
 
+	if err := requireHTTPSURL(ext.getDownloadURL(), "extension download"); err != nil {
+		return err
+	}
+
 	LogInfo("ExtensionStore", "Downloading %s from %s", ext.getDisplayName(), ext.getDownloadURL())
 
-	client := &http.Client{Timeout: 5 * time.Minute}
+	client := NewHTTPClientWithTimeout(5 * time.Minute)
 	resp, err := client.Get(ext.getDownloadURL())
 	if err != nil {
 		return fmt.Errorf("failed to download: %w", err)
@@ -347,8 +374,83 @@ func (s *ExtensionStore) DownloadExtension(extensionID string, destPath string)
 	return nil
 }
 
-// GetCategories returns all available categories
-func (s *ExtensionStore) GetCategories() []string {
+func resolveRegistryURL(input string) (string, error) {
+	input = strings.TrimSpace(input)
+	if input == "" {
+		return "", fmt.Errorf("registry URL is empty")
+	}
+
+	if strings.Contains(input, "raw.githubusercontent.com") {
+		return input, nil
+	}
+
+	const ghPrefix = "https://github.com/"
+	if !strings.HasPrefix(input, ghPrefix) {
+		const ghPrefixHTTP = "http://github.com/"
+		if strings.HasPrefix(input, ghPrefixHTTP) {
+			input = "https://github.com/" + input[len(ghPrefixHTTP):]
+		} else {
+			return input, nil
+		}
+	}
+
+	path := input[len(ghPrefix):]
+	parts := strings.SplitN(path, "/", 3) // owner, repo, [rest]
+	if len(parts) < 2 || parts[0] == "" || parts[1] == "" {
+		return "", fmt.Errorf("invalid GitHub URL: expected github.com/<owner>/<repo>")
+	}
+	owner := parts[0]
+	repo := strings.TrimSuffix(parts[1], ".git")
+
+	branch := resolveGitHubDefaultBranch(owner, repo)
+
+	resolved := fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s/registry.json", owner, repo, branch)
+	LogInfo("ExtensionStore", "Resolved %s → %s (branch: %s)", input, resolved, branch)
+	return resolved, nil
+}
+
+func resolveGitHubDefaultBranch(owner, repo string) string {
+	apiURL := fmt.Sprintf("https://api.github.com/repos/%s/%s", owner, repo)
+	client := NewHTTPClientWithTimeout(10 * time.Second)
+
+	resp, err := client.Get(apiURL)
+	if err != nil {
+		LogWarn("ExtensionStore", "GitHub API request failed for %s/%s: %v – falling back to main", owner, repo, err)
+		return "main"
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		LogWarn("ExtensionStore", "GitHub API returned %d for %s/%s – falling back to main", resp.StatusCode, owner, repo)
+		return "main"
+	}
+
+	var info struct {
+		DefaultBranch string `json:"default_branch"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&info); err != nil || info.DefaultBranch == "" {
+		LogWarn("ExtensionStore", "Could not parse default_branch for %s/%s – falling back to main", owner, repo)
+		return "main"
+	}
+
+	return info.DefaultBranch
+}
+
+func requireHTTPSURL(rawURL string, context string) error {
+	if rawURL == "" {
+		return fmt.Errorf("%s URL is empty", context)
+	}
+	parsed, err := url.Parse(rawURL)
+	if err != nil || parsed.Host == "" {
+		return fmt.Errorf("%s URL is invalid: %s", context, rawURL)
+	}
+	if parsed.Scheme != "https" {
+		return fmt.Errorf("%s URL must use https: %s", context, rawURL)
+	}
+	return nil
+}
+
+func (s *extensionStore) getCategories() []string {
 	return []string{
 		CategoryMetadata,
 		CategoryDownload,
@@ -358,9 +460,8 @@ func (s *ExtensionStore) GetCategories() []string {
 	}
 }
 
-// SearchExtensions searches extensions by query
-func (s *ExtensionStore) SearchExtensions(query string, category string) ([]StoreExtensionResponse, error) {
-	extensions, err := s.GetExtensionsWithStatus()
+func (s *extensionStore) searchExtensions(query string, category string) ([]storeExtensionResponse, error) {
+	extensions, err := s.getExtensionsWithStatus(false)
 	if err != nil {
 		return nil, err
 	}
@@ -369,22 +470,19 @@ func (s *ExtensionStore) SearchExtensions(query string, category string) ([]Stor
 		return extensions, nil
 	}
 
-	var result []StoreExtensionResponse
+	result := make([]storeExtensionResponse, 0, len(extensions))
 	queryLower := toLower(query)
 
 	for _, ext := range extensions {
-		// Filter by category
 		if category != "" && ext.Category != category {
 			continue
 		}
 
-		// Filter by query
 		if query != "" {
 			if !containsIgnoreCase(ext.Name, queryLower) &&
 				!containsIgnoreCase(ext.DisplayName, queryLower) &&
 				!containsIgnoreCase(ext.Description, queryLower) &&
 				!containsIgnoreCase(ext.Author, queryLower) {
-				// Check tags
 				found := false
 				for _, tag := range ext.Tags {
 					if containsIgnoreCase(tag, queryLower) {
@@ -404,8 +502,7 @@ func (s *ExtensionStore) SearchExtensions(query string, category string) ([]Stor
 	return result, nil
 }
 
-// ClearCache clears the in-memory and disk cache
-func (s *ExtensionStore) ClearCache() {
+func (s *extensionStore) clearCache() {
 	s.cacheMu.Lock()
 	defer s.cacheMu.Unlock()
 
@@ -420,7 +517,6 @@ func (s *ExtensionStore) ClearCache() {
 	LogInfo("ExtensionStore", "Cache cleared")
 }
 
-// Helper: case-insensitive contains
 func containsIgnoreCase(s, substr string) bool {
 	return containsStr(toLower(s), substr)
 }

go_backend/extension_test.go

@@ -99,7 +99,7 @@ func TestIsDomainAllowed(t *testing.T) {
 
 func TestExtensionRuntime_NetworkSandbox(t *testing.T) {
 	// Create a mock extension with limited network permissions
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID: "test-ext",
 		Manifest: &ExtensionManifest{
 			Name: "test-ext",
@@ -110,9 +110,8 @@ func TestExtensionRuntime_NetworkSandbox(t *testing.T) {
 		DataDir: t.TempDir(),
 	}
 
-	runtime := NewExtensionRuntime(ext)
+	runtime := newExtensionRuntime(ext)
 
-	// Test allowed domains
 	if err := runtime.validateDomain("https://api.allowed.com/path"); err != nil {
 		t.Errorf("Expected api.allowed.com to be allowed, got error: %v", err)
 	}
@@ -121,7 +120,6 @@ func TestExtensionRuntime_NetworkSandbox(t *testing.T) {
 		t.Errorf("Expected sub.wildcard.com to be allowed (wildcard), got error: %v", err)
 	}
 
-	// Test blocked domains
 	if err := runtime.validateDomain("https://blocked.com/path"); err == nil {
 		t.Error("Expected blocked.com to be denied")
 	}
@@ -134,20 +132,19 @@ func TestExtensionRuntime_NetworkSandbox(t *testing.T) {
 func TestExtensionRuntime_FileSandbox(t *testing.T) {
 	tempDir := t.TempDir()
 
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID: "test-ext",
 		Manifest: &ExtensionManifest{
 			Name: "test-ext",
 			Permissions: ExtensionPermissions{
-				File: true, // Enable file permission for test
+				File: true,
 			},
 		},
 		DataDir: tempDir,
 	}
 
-	runtime := NewExtensionRuntime(ext)
+	runtime := newExtensionRuntime(ext)
 
-	// Test valid path within sandbox
 	validPath, err := runtime.validatePath("test.txt")
 	if err != nil {
 		t.Errorf("Expected relative path to be valid, got error: %v", err)
@@ -156,13 +153,11 @@ func TestExtensionRuntime_FileSandbox(t *testing.T) {
 		t.Error("Expected non-empty path")
 	}
 
-	// Test path traversal attack
 	_, err = runtime.validatePath("../../../etc/passwd")
 	if err == nil {
 		t.Error("Expected path traversal to be blocked")
 	}
 
-	// Test nested path within sandbox (should be allowed)
 	nestedPath, err := runtime.validatePath("subdir/file.txt")
 	if err != nil {
 		t.Errorf("Expected nested path to be valid, got error: %v", err)
@@ -171,31 +166,28 @@ func TestExtensionRuntime_FileSandbox(t *testing.T) {
 		t.Error("Expected non-empty nested path")
 	}
 
-	// Test absolute path should be blocked (security fix)
-	// Use platform-appropriate absolute path
 	var absPath string
 	if filepath.IsAbs("C:\\Windows\\System32") {
-		absPath = "C:\\Windows\\System32\\test.txt" // Windows
+		absPath = "C:\\Windows\\System32\\test.txt"
 	} else {
-		absPath = "/etc/passwd" // Unix
+		absPath = "/etc/passwd"
 	}
 	_, err = runtime.validatePath(absPath)
 	if err == nil {
 		t.Error("Expected absolute path to be blocked")
 	}
 
-	// Test that extension without file permission is blocked
-	extNoFile := &LoadedExtension{
+	extNoFile := &loadedExtension{
 		ID: "test-ext-no-file",
 		Manifest: &ExtensionManifest{
 			Name: "test-ext-no-file",
 			Permissions: ExtensionPermissions{
-				File: false, // No file permission
+				File: false,
 			},
 		},
 		DataDir: tempDir,
 	}
-	runtimeNoFile := NewExtensionRuntime(extNoFile)
+	runtimeNoFile := newExtensionRuntime(extNoFile)
 	_, err = runtimeNoFile.validatePath("test.txt")
 	if err == nil {
 		t.Error("Expected file access to be denied without file permission")
@@ -203,7 +195,7 @@ func TestExtensionRuntime_FileSandbox(t *testing.T) {
 }
 
 func TestExtensionRuntime_UtilityFunctions(t *testing.T) {
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID: "test-ext",
 		Manifest: &ExtensionManifest{
 			Name: "test-ext",
@@ -211,11 +203,10 @@ func TestExtensionRuntime_UtilityFunctions(t *testing.T) {
 		DataDir: t.TempDir(),
 	}
 
-	runtime := NewExtensionRuntime(ext)
+	runtime := newExtensionRuntime(ext)
 	vm := goja.New()
 	runtime.RegisterAPIs(vm)
 
-	// Test base64 encode/decode
 	result, err := vm.RunString(`utils.base64Encode("hello")`)
 	if err != nil {
 		t.Fatalf("base64Encode failed: %v", err)
@@ -232,7 +223,6 @@ func TestExtensionRuntime_UtilityFunctions(t *testing.T) {
 		t.Errorf("Expected 'hello', got '%s'", result.String())
 	}
 
-	// Test MD5
 	result, err = vm.RunString(`utils.md5("hello")`)
 	if err != nil {
 		t.Fatalf("md5 failed: %v", err)
@@ -241,7 +231,6 @@ func TestExtensionRuntime_UtilityFunctions(t *testing.T) {
 		t.Errorf("Expected '5d41402abc4b2a76b9719d911017c592', got '%s'", result.String())
 	}
 
-	// Test JSON parse/stringify
 	result, err = vm.RunString(`utils.stringifyJSON({name: "test", value: 123})`)
 	if err != nil {
 		t.Fatalf("stringifyJSON failed: %v", err)
@@ -254,7 +243,7 @@ func TestExtensionRuntime_UtilityFunctions(t *testing.T) {
 
 func TestExtensionRuntime_SSRFProtection(t *testing.T) {
 	// Create extension with limited network permissions
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID: "test-ext",
 		Manifest: &ExtensionManifest{
 			Name: "test-ext",
@@ -265,9 +254,8 @@ func TestExtensionRuntime_SSRFProtection(t *testing.T) {
 		DataDir: t.TempDir(),
 	}
 
-	runtime := NewExtensionRuntime(ext)
+	runtime := newExtensionRuntime(ext)
 
-	// Test that private IPs are blocked (SSRF protection)
 	privateIPs := []string{
 		"http://localhost/admin",
 		"http://127.0.0.1/admin",
@@ -285,7 +273,6 @@ func TestExtensionRuntime_SSRFProtection(t *testing.T) {
 		}
 	}
 
-	// Test that allowed public domain still works
 	if err := runtime.validateDomain("https://api.example.com/path"); err != nil {
 		t.Errorf("Expected api.example.com to be allowed, got error: %v", err)
 	}
@@ -296,7 +283,6 @@ func TestIsPrivateIP(t *testing.T) {
 		host     string
 		expected bool
 	}{
-		// Private IPs should be blocked
 		{"localhost", true},
 		{"127.0.0.1", true},
 		{"127.0.0.2", true},
@@ -306,18 +292,17 @@ func TestIsPrivateIP(t *testing.T) {
 		{"172.31.255.255", true},
 		{"192.168.0.1", true},
 		{"192.168.255.255", true},
-		{"169.254.169.254", true}, // AWS metadata
+		{"169.254.169.254", true},
 		{"router.local", true},
 		{"mydevice.local", true},
 
-		// Public IPs should be allowed
 		{"8.8.8.8", false},
 		{"1.1.1.1", false},
 		{"api.example.com", false},
 		{"google.com", false},
-		{"172.15.0.1", false},  // Just outside 172.16-31 range
-		{"172.32.0.1", false},  // Just outside 172.16-31 range
-		{"192.167.0.1", false}, // Not 192.168.x.x
+		{"172.15.0.1", false},
+		{"172.32.0.1", false},
+		{"192.167.0.1", false},
 	}
 
 	for _, tt := range tests {

go_backend/extension_timeout.go

@@ -1,16 +1,15 @@
-// Package gobackend provides timeout execution for extension JS code
 package gobackend
 
 import (
 	"context"
 	"fmt"
+	"runtime/debug"
 	"sync"
 	"time"
 
 	"github.com/dop251/goja"
 )
 
-// JSExecutionError represents an error during JS execution
 type JSExecutionError struct {
 	Message   string
 	IsTimeout bool
@@ -20,9 +19,11 @@ func (e *JSExecutionError) Error() string {
 	return e.Message
 }
 
-// RunWithTimeout executes JavaScript code with a timeout
-// Returns the result value and any error (including timeout)
 func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goja.Value, error) {
+	if vm == nil {
+		return nil, fmt.Errorf("extension runtime unavailable")
+	}
+
 	if timeout <= 0 {
 		timeout = DefaultJSTimeout
 	}
@@ -30,22 +31,18 @@ func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goj
 	ctx, cancel := context.WithTimeout(context.Background(), timeout)
 	defer cancel()
 
-	// Channel to receive result
 	type result struct {
 		value goja.Value
 		err   error
 	}
 	resultCh := make(chan result, 1)
 
-	// Track if we've interrupted
 	var interrupted bool
 	var interruptMu sync.Mutex
 
-	// Run script in goroutine
 	go func() {
 		defer func() {
 			if r := recover(); r != nil {
-				// Check if this was our interrupt
 				interruptMu.Lock()
 				wasInterrupted := interrupted
 				interruptMu.Unlock()
@@ -56,6 +53,7 @@ func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goj
 						IsTimeout: true,
 					}}
 				} else {
+					GoLog("[extensionRuntime] panic during JS execution: %v\n%s\n", r, string(debug.Stack()))
 					resultCh <- result{nil, fmt.Errorf("panic during execution: %v", r)}
 				}
 			}
@@ -65,22 +63,23 @@ func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goj
 		resultCh <- result{val, err}
 	}()
 
-	// Wait for result or timeout
 	select {
 	case res := <-resultCh:
 		return res.value, res.err
 	case <-ctx.Done():
-		// Timeout - interrupt the VM
 		interruptMu.Lock()
 		interrupted = true
 		interruptMu.Unlock()
 
 		vm.Interrupt("execution timeout")
 
-		// Wait a bit for the goroutine to finish
+		// MUST wait for the goroutine to finish before returning.
+		// The Goja VM is NOT thread-safe — if we return while the goroutine
+		// is still executing JS (e.g. blocked on an HTTP call), the next
+		// caller will access the VM concurrently and crash with a nil
+		// pointer dereference.
 		select {
 		case res := <-resultCh:
-			// If we got a result after interrupt, it might be the timeout error
 			if res.err != nil {
 				return nil, res.err
 			}
@@ -88,8 +87,10 @@ func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goj
 				Message:   "execution timeout exceeded",
 				IsTimeout: true,
 			}
-		case <-time.After(1 * time.Second):
-			// Force return timeout error
+		case <-time.After(60 * time.Second):
+			// Goroutine is truly stuck (e.g. HTTP read with no timeout).
+			// Log a warning — the VM should NOT be reused after this.
+			GoLog("[extensionRuntime] WARNING: JS goroutine did not exit within 60s after interrupt, VM may be unsafe\n")
 			return nil, &JSExecutionError{
 				Message:   "execution timeout exceeded (force)",
 				IsTimeout: true,
@@ -103,13 +104,13 @@ func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goj
 func RunWithTimeoutAndRecover(vm *goja.Runtime, script string, timeout time.Duration) (goja.Value, error) {
 	result, err := RunWithTimeout(vm, script, timeout)
 
-	// Clear any interrupt state so VM can be reused
-	vm.ClearInterrupt()
+	if vm != nil {
+		vm.ClearInterrupt()
+	}
 
 	return result, err
 }
 
-// IsTimeoutError checks if an error is a timeout error
 func IsTimeoutError(err error) bool {
 	if jsErr, ok := err.(*JSExecutionError); ok {
 		return jsErr.IsTimeout

go_backend/filename.go

@@ -3,28 +3,35 @@ package gobackend
 import (
 	"fmt"
 	"regexp"
+	"strconv"
 	"strings"
+	"time"
 )
 
-var invalidChars = regexp.MustCompile(`[<>:"/\\|?*\x00-\x1f]`)
+var (
+	invalidChars                   = regexp.MustCompile(`[<>:"/\\|?*\x00-\x1f]`)
+	multiUnderscore                = regexp.MustCompile(`_+`)
+	formattedNumberPlaceholderExpr = regexp.MustCompile(`\{(track|disc):([0-9]+)\}`)
+	dateFormatPlaceholderExpr      = regexp.MustCompile(`\{date:([^{}]+)\}`)
+	yearPattern                    = regexp.MustCompile(`\d{4}`)
+)
 
 func sanitizeFilename(filename string) string {
 	sanitized := invalidChars.ReplaceAllString(filename, "_")
-	
+
 	sanitized = strings.TrimSpace(sanitized)
 	sanitized = strings.Trim(sanitized, ".")
-	
-	multiUnderscore := regexp.MustCompile(`_+`)
+
 	sanitized = multiUnderscore.ReplaceAllString(sanitized, "_")
-	
+
 	if len(sanitized) > 200 {
 		sanitized = sanitized[:200]
 	}
-	
+
 	if sanitized == "" {
 		sanitized = "untitled"
 	}
-	
+
 	return sanitized
 }
 
@@ -32,45 +39,120 @@ func buildFilenameFromTemplate(template string, metadata map[string]interface{})
 	if template == "" {
 		template = "{artist} - {title}"
 	}
-	
-	result := template
-	
-	placeholders := map[string]string{
-		"{title}":  getString(metadata, "title"),
-		"{artist}": getString(metadata, "artist"),
-		"{album}":  getString(metadata, "album"),
-		"{track}":  formatTrackNumber(getInt(metadata, "track")),
-		"{year}":   getString(metadata, "year"),
-		"{disc}":   formatDiscNumber(getInt(metadata, "disc")),
+
+	result := replaceFormattedNumberPlaceholders(template, metadata)
+	result = replaceDateFormatPlaceholders(result, metadata)
+
+	dateValue := getDateValue(metadata)
+	yearValue := getString(metadata, "year")
+	if yearValue == "" {
+		yearValue = extractYear(dateValue)
 	}
-	
+
+	placeholders := map[string]string{
+		"{title}":     getString(metadata, "title"),
+		"{artist}":    getString(metadata, "artist"),
+		"{album}":     getString(metadata, "album"),
+		"{track}":     formatTrackNumber(getInt(metadata, "track")),
+		"{track_raw}": formatRawNumber(getInt(metadata, "track")),
+		"{year}":      yearValue,
+		"{date}":      dateValue,
+		"{disc}":      formatDiscNumber(getInt(metadata, "disc")),
+		"{disc_raw}":  formatRawNumber(getInt(metadata, "disc")),
+	}
+
 	for placeholder, value := range placeholders {
 		result = strings.ReplaceAll(result, placeholder, value)
 	}
-	
+
 	return result
 }
 
+func replaceFormattedNumberPlaceholders(template string, metadata map[string]interface{}) string {
+	return formattedNumberPlaceholderExpr.ReplaceAllStringFunc(template, func(match string) string {
+		parts := formattedNumberPlaceholderExpr.FindStringSubmatch(match)
+		if len(parts) != 3 {
+			return ""
+		}
+
+		number := getInt(metadata, parts[1])
+		width, err := strconv.Atoi(parts[2])
+		if err != nil {
+			return ""
+		}
+
+		return formatNumberWithWidth(number, width)
+	})
+}
+
+func replaceDateFormatPlaceholders(template string, metadata map[string]interface{}) string {
+	return dateFormatPlaceholderExpr.ReplaceAllStringFunc(template, func(match string) string {
+		parts := dateFormatPlaceholderExpr.FindStringSubmatch(match)
+		if len(parts) != 2 {
+			return ""
+		}
+
+		return formatDateWithPattern(getDateValue(metadata), parts[1])
+	})
+}
+
+func getDateValue(metadata map[string]interface{}) string {
+	date := getString(metadata, "date")
+	if date != "" {
+		return date
+	}
+
+	releaseDate := getString(metadata, "release_date")
+	if releaseDate != "" {
+		return releaseDate
+	}
+
+	return getString(metadata, "year")
+}
+
 func getString(m map[string]interface{}, key string) string {
 	if v, ok := m[key]; ok {
-		if s, ok := v.(string); ok {
-			return strings.TrimSpace(s)
+		switch value := v.(type) {
+		case string:
+			return strings.TrimSpace(value)
+		case int:
+			return strconv.Itoa(value)
+		case int64:
+			return strconv.FormatInt(value, 10)
+		case float64:
+			return strconv.Itoa(int(value))
 		}
 	}
 	return ""
 }
 
 func getInt(m map[string]interface{}, key string) int {
-	if v, ok := m[key]; ok {
-		switch n := v.(type) {
-		case int:
-			return n
-		case int64:
-			return int(n)
-		case float64:
-			return int(n)
+	candidateKeys := []string{key}
+	switch key {
+	case "track":
+		candidateKeys = append(candidateKeys, "track_number")
+	case "disc":
+		candidateKeys = append(candidateKeys, "disc_number")
+	}
+
+	for _, candidate := range candidateKeys {
+		if v, ok := m[candidate]; ok {
+			switch n := v.(type) {
+			case int:
+				return n
+			case int64:
+				return int(n)
+			case float64:
+				return int(n)
+			case string:
+				parsed, err := strconv.Atoi(strings.TrimSpace(n))
+				if err == nil {
+					return parsed
+				}
+			}
 		}
 	}
+
 	return 0
 }
 
@@ -88,6 +170,129 @@ func formatDiscNumber(n int) string {
 	return fmt.Sprintf("%d", n)
 }
 
+func formatRawNumber(n int) string {
+	if n <= 0 {
+		return ""
+	}
+	return fmt.Sprintf("%d", n)
+}
+
+func formatNumberWithWidth(n int, width int) string {
+	if n <= 0 || width <= 0 {
+		return ""
+	}
+	if width <= 1 {
+		return formatRawNumber(n)
+	}
+	return fmt.Sprintf("%0*d", width, n)
+}
+
+func formatDateWithPattern(rawDate string, strftimePattern string) string {
+	if rawDate == "" || strftimePattern == "" {
+		return ""
+	}
+
+	parsedDate, ok := parseMetadataDate(rawDate)
+	if !ok {
+		return ""
+	}
+
+	goLayout := convertStrftimeToGoLayout(strftimePattern)
+	if goLayout == "" {
+		return ""
+	}
+
+	return parsedDate.Format(goLayout)
+}
+
+func parseMetadataDate(rawDate string) (time.Time, bool) {
+	clean := strings.TrimSpace(rawDate)
+	if clean == "" {
+		return time.Time{}, false
+	}
+
+	layouts := []string{
+		time.RFC3339Nano,
+		time.RFC3339,
+		"2006-01-02",
+		"2006-01",
+		"2006",
+		"2006/01/02",
+		"2006/01",
+		"2006.01.02",
+		"2006.01",
+	}
+
+	for _, layout := range layouts {
+		parsed, err := time.Parse(layout, clean)
+		if err == nil {
+			return parsed, true
+		}
+	}
+
+	if len(clean) >= 10 {
+		parsed, err := time.Parse("2006-01-02", clean[:10])
+		if err == nil {
+			return parsed, true
+		}
+	}
+
+	yearMatch := yearPattern.FindString(clean)
+	if yearMatch == "" {
+		return time.Time{}, false
+	}
+
+	year, err := strconv.Atoi(yearMatch)
+	if err != nil || year <= 0 {
+		return time.Time{}, false
+	}
+
+	return time.Date(year, time.January, 1, 0, 0, 0, 0, time.UTC), true
+}
+
+func convertStrftimeToGoLayout(pattern string) string {
+	if pattern == "" {
+		return ""
+	}
+
+	var builder strings.Builder
+	for i := 0; i < len(pattern); i++ {
+		ch := pattern[i]
+		if ch != '%' {
+			builder.WriteByte(ch)
+			continue
+		}
+
+		if i+1 >= len(pattern) {
+			builder.WriteByte('%')
+			break
+		}
+
+		i++
+		switch pattern[i] {
+		case 'Y':
+			builder.WriteString("2006")
+		case 'y':
+			builder.WriteString("06")
+		case 'm':
+			builder.WriteString("01")
+		case 'd':
+			builder.WriteString("02")
+		case 'b':
+			builder.WriteString("Jan")
+		case 'B':
+			builder.WriteString("January")
+		case '%':
+			builder.WriteByte('%')
+		default:
+			builder.WriteByte('%')
+			builder.WriteByte(pattern[i])
+		}
+	}
+
+	return builder.String()
+}
+
 func extractYear(date string) string {
 	if len(date) >= 4 {
 		return date[:4]

go_backend/filename_test.go

@@ -0,0 +1,85 @@
+package gobackend
+
+import "testing"
+
+func TestBuildFilenameFromTemplate_WithRawTrackAndDisc(t *testing.T) {
+	metadata := map[string]interface{}{
+		"title":  "Song Name",
+		"artist": "Artist Name",
+		"album":  "Album Name",
+		"track":  1,
+		"disc":   2,
+		"year":   "2025",
+	}
+
+	formatted := buildFilenameFromTemplate(
+		"{artist} - {track} - {track_raw} - d{disc} - d{disc_raw} - {title}",
+		metadata,
+	)
+
+	expected := "Artist Name - 01 - 1 - d2 - d2 - Song Name"
+	if formatted != expected {
+		t.Fatalf("expected %q, got %q", expected, formatted)
+	}
+}
+
+func TestBuildFilenameFromTemplate_RawPlaceholdersEmptyWhenZero(t *testing.T) {
+	metadata := map[string]interface{}{
+		"title":  "Song Name",
+		"artist": "Artist Name",
+		"track":  0,
+		"disc":   0,
+	}
+
+	formatted := buildFilenameFromTemplate("{track_raw}-{disc_raw}-{title}", metadata)
+	expected := "--Song Name"
+	if formatted != expected {
+		t.Fatalf("expected %q, got %q", expected, formatted)
+	}
+}
+
+func TestBuildFilenameFromTemplate_InlineNumberFormatting(t *testing.T) {
+	metadata := map[string]interface{}{
+		"track": 3,
+		"disc":  2,
+	}
+
+	formatted := buildFilenameFromTemplate("{track:1}-{track:02}-{disc:03}", metadata)
+	expected := "3-03-002"
+	if formatted != expected {
+		t.Fatalf("expected %q, got %q", expected, formatted)
+	}
+}
+
+func TestBuildFilenameFromTemplate_DateStrftimeFormatting(t *testing.T) {
+	metadata := map[string]interface{}{
+		"artist":       "Artist Name",
+		"title":        "Song Name",
+		"release_date": "2024-03-09",
+		"track_number": 7,
+		"disc_number":  1,
+	}
+
+	formatted := buildFilenameFromTemplate(
+		"{artist} - {track:02} - {title} - {date:%Y-%m-%d} - {year}",
+		metadata,
+	)
+	expected := "Artist Name - 07 - Song Name - 2024-03-09 - 2024"
+	if formatted != expected {
+		t.Fatalf("expected %q, got %q", expected, formatted)
+	}
+}
+
+func TestBuildFilenameFromTemplate_DateStrftimeFormattingWithYearOnly(t *testing.T) {
+	metadata := map[string]interface{}{
+		"artist": "Artist Name",
+		"title":  "Song Name",
+		"date":   "2019",
+	}
+
+	formatted := buildFilenameFromTemplate("{date:%Y}-{date:%m}-{date:%d}", metadata)
+	expected := "2019-01-01"
+	if formatted != expected {
+		t.Fatalf("expected %q, got %q", expected, formatted)
+	}
+}

go_backend/go.mod

@@ -1,23 +1,29 @@
 module github.com/zarz/spotiflac_android/go_backend
 
-go 1.24.0
+go 1.25.0
 
-toolchain go1.24.5
+toolchain go1.25.8
 
 require (
-	github.com/dop251/goja v0.0.0-20260106131823-651366fbe6e3
-	github.com/go-flac/flacpicture v0.3.0
-	github.com/go-flac/flacvorbis v0.2.0
-	github.com/go-flac/go-flac v1.0.0
+	github.com/dop251/goja v0.0.0-20260311135729-065cd970411c
+	github.com/go-flac/flacpicture/v2 v2.0.2
+	github.com/go-flac/flacvorbis/v2 v2.0.2
+	github.com/go-flac/go-flac/v2 v2.0.4
+	github.com/refraction-networking/utls v1.8.2
+	golang.org/x/mobile v0.0.0-20260312152759-81488f6aeb60
+	golang.org/x/net v0.52.0
+	golang.org/x/text v0.35.0
 )
 
 require (
-	github.com/dlclark/regexp2 v1.11.4 // indirect
-	github.com/go-sourcemap/sourcemap v2.1.3+incompatible // indirect
-	github.com/google/pprof v0.0.0-20230207041349-798e818bf904 // indirect
-	golang.org/x/mobile v0.0.0-20251209145715-2553ed8ce294 // indirect
-	golang.org/x/mod v0.31.0 // indirect
-	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/text v0.3.8 // indirect
-	golang.org/x/tools v0.40.0 // indirect
+	github.com/andybalholm/brotli v1.2.0 // indirect
+	github.com/dlclark/regexp2 v1.11.5 // indirect
+	github.com/go-sourcemap/sourcemap v2.1.4+incompatible // indirect
+	github.com/google/pprof v0.0.0-20260302011040-a15ffb7f9dcc // indirect
+	github.com/klauspost/compress v1.18.5 // indirect
+	golang.org/x/crypto v0.49.0 // indirect
+	golang.org/x/mod v0.34.0 // indirect
+	golang.org/x/sync v0.20.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
+	golang.org/x/tools v0.43.0 // indirect
 )

go_backend/go.sum

@@ -1,28 +1,52 @@
 github.com/Masterminds/semver/v3 v3.2.1 h1:RN9w6+7QoMeJVGyfmbcgs28Br8cvmnucEXnY0rYXWg0=
 github.com/Masterminds/semver/v3 v3.2.1/go.mod h1:qvl/7zhW3nngYb5+80sSMF+FG2BjYrf8m9wsX0PNOMQ=
-github.com/dlclark/regexp2 v1.11.4 h1:rPYF9/LECdNymJufQKmri9gV604RvvABwgOA8un7yAo=
-github.com/dlclark/regexp2 v1.11.4/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
-github.com/dop251/goja v0.0.0-20260106131823-651366fbe6e3 h1:bVp3yUzvSAJzu9GqID+Z96P+eu5TKnIMJSV4QaZMauM=
-github.com/dop251/goja v0.0.0-20260106131823-651366fbe6e3/go.mod h1:MxLav0peU43GgvwVgNbLAj1s/bSGboKkhuULvq/7hx4=
-github.com/go-flac/flacpicture v0.3.0 h1:LkmTxzFLIynwfhHiZsX0s8xcr3/u33MzvV89u+zOT8I=
-github.com/go-flac/flacpicture v0.3.0/go.mod h1:DPbrzVYQ3fJcvSgLFp9HXIrEQEdfdk/+m0nQCzwodZI=
-github.com/go-flac/flacvorbis v0.2.0 h1:KH0xjpkNTXFER4cszH4zeJxYcrHbUobz/RticWGOESs=
-github.com/go-flac/flacvorbis v0.2.0/go.mod h1:uIysHOtuU7OLGoCRG92bvnkg7QEqHx19qKRV6K1pBrI=
-github.com/go-flac/go-flac v1.0.0 h1:6qI9XOVLcO50xpzm3nXvO31BgDgHhnr/p/rER/K/doY=
-github.com/go-flac/go-flac v1.0.0/go.mod h1:WnZhcpmq4u1UdZMNn9LYSoASpWOCMOoxXxcWEHSzkW8=
-github.com/go-sourcemap/sourcemap v2.1.3+incompatible h1:W1iEw64niKVGogNgBN3ePyLFfuisuzeidWPMPWmECqU=
-github.com/go-sourcemap/sourcemap v2.1.3+incompatible/go.mod h1:F8jJfvm2KbVjc5NqelyYJmf/v5J0dwNLS2mL4sNA1Jg=
-github.com/google/pprof v0.0.0-20230207041349-798e818bf904 h1:4/hN5RUoecvl+RmJRE2YxKWtnnQls6rQjjW5oV7qg2U=
-github.com/google/pprof v0.0.0-20230207041349-798e818bf904/go.mod h1:uglQLonpP8qtYCYyzA+8c/9qtqgA3qsXGYqCPKARAFg=
-golang.org/x/mobile v0.0.0-20251209145715-2553ed8ce294 h1:Cr6kbEvA6nqvdHynE4CtVKlqpZB9dS1Jva/6IsHA19g=
-golang.org/x/mobile v0.0.0-20251209145715-2553ed8ce294/go.mod h1:RdZ+3sb4CVgpCFnzv+I4haEpwqFfsfzlLHs3L7ok+e0=
-golang.org/x/mod v0.31.0 h1:HaW9xtz0+kOcWKwli0ZXy79Ix+UW/vOfmWI5QVd2tgI=
-golang.org/x/mod v0.31.0/go.mod h1:43JraMp9cGx1Rx3AqioxrbrhNsLl2l/iNAvuBkrezpg=
-golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
-golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
-golang.org/x/text v0.3.8 h1:nAL+RVCQ9uMn3vJZbV+MRnydTJFPf8qqY42YiA6MrqY=
-golang.org/x/text v0.3.8/go.mod h1:E6s5w1FMmriuDzIBO73fBruAKo1PCIq6d2Q6DHfQ8WQ=
-golang.org/x/tools v0.40.0 h1:yLkxfA+Qnul4cs9QA3KnlFu0lVmd8JJfoq+E41uSutA=
-golang.org/x/tools v0.40.0/go.mod h1:Ik/tzLRlbscWpqqMRjyWYDisX8bG13FrdXp3o4Sr9lc=
+github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
+github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dlclark/regexp2 v1.11.5 h1:Q/sSnsKerHeCkc/jSTNq1oCm7KiVgUMZRDUoRu0JQZQ=
+github.com/dlclark/regexp2 v1.11.5/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
+github.com/dop251/goja v0.0.0-20260311135729-065cd970411c h1:OcLmPfx1T1RmZVHHFwWMPaZDdRf0DBMZOFMVWJa7Pdk=
+github.com/dop251/goja v0.0.0-20260311135729-065cd970411c/go.mod h1:MxLav0peU43GgvwVgNbLAj1s/bSGboKkhuULvq/7hx4=
+github.com/go-flac/flacpicture/v2 v2.0.2 h1:HCaJIVZpxnpdWs6G3ECEVRelzqS5xOi1Ba1AGmtXbzE=
+github.com/go-flac/flacpicture/v2 v2.0.2/go.mod h1:DMZBPWPAmdLqNhqFSy5ZBs9wyBzOekXutGfP7/TFCuo=
+github.com/go-flac/flacvorbis/v2 v2.0.2 h1:xCL3OhxrxWkHrbWUBvGNe+6FQ03yLmBbz0v5z4V2PoQ=
+github.com/go-flac/flacvorbis/v2 v2.0.2/go.mod h1:SwTB5gs13VaM/N7rstwPoUsPibiMKklgwybYP9dYo2g=
+github.com/go-flac/go-flac/v2 v2.0.4 h1:atf/kFa8U9idtkA//NO22XGr+MzQLeXZecnmP9sYBf0=
+github.com/go-flac/go-flac/v2 v2.0.4/go.mod h1:sYOlTKxutMW0RDYF+KlD6Zn+VOCZlIFQG/r/usPveCs=
+github.com/go-sourcemap/sourcemap v2.1.4+incompatible h1:a+iTbH5auLKxaNwQFg0B+TCYl6lbukKPc7b5x0n1s6Q=
+github.com/go-sourcemap/sourcemap v2.1.4+incompatible/go.mod h1:F8jJfvm2KbVjc5NqelyYJmf/v5J0dwNLS2mL4sNA1Jg=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/pprof v0.0.0-20260302011040-a15ffb7f9dcc h1:VBbFa1lDYWEeV5FZKUiYKYT0VxCp9twUmmaq9eb8sXw=
+github.com/google/pprof v0.0.0-20260302011040-a15ffb7f9dcc/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
+github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE=
+github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/refraction-networking/utls v1.8.2 h1:j4Q1gJj0xngdeH+Ox/qND11aEfhpgoEvV+S9iJ2IdQo=
+github.com/refraction-networking/utls v1.8.2/go.mod h1:jkSOEkLqn+S/jtpEHPOsVv/4V4EVnelwbMQl4vCWXAM=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
+github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
+golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
+golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
+golang.org/x/mobile v0.0.0-20260312152759-81488f6aeb60 h1:MOzyaj0wu2xneBkzkg9LHNYjDBB4W5vP043A2SYQRPA=
+golang.org/x/mobile v0.0.0-20260312152759-81488f6aeb60/go.mod h1:th6VJvzjMbrYF8SduQY5rpD0HG0GleGxjadkqSxFs3k=
+golang.org/x/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI=
+golang.org/x/mod v0.34.0/go.mod h1:ykgH52iCZe79kzLLMhyCUzhMci+nQj+0XkbXpNYtVjY=
+golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
+golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
+golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
+golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
+golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
 gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

go_backend/httputil.go

@@ -11,15 +11,12 @@ import (
 	"net/url"
 	"strconv"
 	"strings"
+	"sync"
 	"syscall"
 	"time"
 )
 
-// getRandomUserAgent generates a random Windows Chrome User-Agent string
-// Uses modern Chrome format with build and patch numbers
-// Windows 11 still reports as "Windows NT 10.0" for compatibility
 func getRandomUserAgent() string {
-	// Chrome version 120-145 (modern range)
 	chromeVersion := rand.Intn(26) + 120
 	chromeBuild := rand.Intn(1500) + 6000
 	chromePatch := rand.Intn(200) + 100
@@ -34,13 +31,23 @@ func getRandomUserAgent() string {
 
 const (
 	DefaultTimeout    = 60 * time.Second
-	DownloadTimeout   = 120 * time.Second
+	DownloadTimeout   = 24 * time.Hour
 	SongLinkTimeout   = 30 * time.Second
 	DefaultMaxRetries = 3
 	DefaultRetryDelay = 1 * time.Second
+	Second            = time.Second
+)
+
+type NetworkCompatibilityOptions struct {
+	AllowHTTP   bool
+	InsecureTLS bool
+}
+
+var (
+	networkCompatibilityMu      sync.RWMutex
+	networkCompatibilityOptions NetworkCompatibilityOptions
 )
 
-// Shared transport with connection pooling to prevent TCP exhaustion
 var sharedTransport = &http.Transport{
 	DialContext: (&net.Dialer{
 		Timeout:   30 * time.Second,
@@ -59,19 +66,44 @@ var sharedTransport = &http.Transport{
 	DisableCompression:    true,
 }
 
+var metadataTransport = &http.Transport{
+	DialContext: (&net.Dialer{
+		Timeout:   30 * time.Second,
+		KeepAlive: 30 * time.Second,
+	}).DialContext,
+	MaxIdleConns:          30,
+	MaxIdleConnsPerHost:   5,
+	MaxConnsPerHost:       10,
+	IdleConnTimeout:       90 * time.Second,
+	TLSHandshakeTimeout:   10 * time.Second,
+	ExpectContinueTimeout: 1 * time.Second,
+	DisableKeepAlives:     false,
+	ForceAttemptHTTP2:     true,
+	WriteBufferSize:       32 * 1024,
+	ReadBufferSize:        32 * 1024,
+	DisableCompression:    true,
+}
+
 var sharedClient = &http.Client{
-	Transport: sharedTransport,
+	Transport: newCompatibilityTransport(sharedTransport),
 	Timeout:   DefaultTimeout,
 }
 
 var downloadClient = &http.Client{
-	Transport: sharedTransport,
+	Transport: newCompatibilityTransport(sharedTransport),
 	Timeout:   DownloadTimeout,
 }
 
 func NewHTTPClientWithTimeout(timeout time.Duration) *http.Client {
 	return &http.Client{
-		Transport: sharedTransport,
+		Transport: newCompatibilityTransport(sharedTransport),
+		Timeout:   timeout,
+	}
+}
+
+func NewMetadataHTTPClient(timeout time.Duration) *http.Client {
+	return &http.Client{
+		Transport: newCompatibilityTransport(metadataTransport),
 		Timeout:   timeout,
 	}
 }
@@ -84,12 +116,114 @@ func GetDownloadClient() *http.Client {
 	return downloadClient
 }
 
-// CloseIdleConnections closes idle connections in the shared transport
 func CloseIdleConnections() {
 	sharedTransport.CloseIdleConnections()
+	metadataTransport.CloseIdleConnections()
+}
+
+func SetNetworkCompatibilityOptions(allowHTTP, insecureTLS bool) {
+	networkCompatibilityMu.Lock()
+	networkCompatibilityOptions = NetworkCompatibilityOptions{
+		AllowHTTP:   allowHTTP,
+		InsecureTLS: insecureTLS,
+	}
+	networkCompatibilityMu.Unlock()
+
+	applyTLSCompatibility(sharedTransport, insecureTLS)
+	applyTLSCompatibility(metadataTransport, insecureTLS)
+	CloseIdleConnections()
+
+	GoLog("[HTTP] Network compatibility options updated: allow_http=%v insecure_tls=%v\n", allowHTTP, insecureTLS)
+}
+
+func GetNetworkCompatibilityOptions() NetworkCompatibilityOptions {
+	networkCompatibilityMu.RLock()
+	defer networkCompatibilityMu.RUnlock()
+	return networkCompatibilityOptions
+}
+
+func applyTLSCompatibility(transport *http.Transport, insecureTLS bool) {
+	if insecureTLS {
+		cfg := &tls.Config{InsecureSkipVerify: true}
+		if transport.TLSClientConfig != nil {
+			cfg = transport.TLSClientConfig.Clone()
+			cfg.InsecureSkipVerify = true
+		}
+		transport.TLSClientConfig = cfg
+		return
+	}
+
+	transport.TLSClientConfig = nil
+}
+
+type compatibilityTransport struct {
+	base http.RoundTripper
+}
+
+func newCompatibilityTransport(base http.RoundTripper) http.RoundTripper {
+	return &compatibilityTransport{base: base}
+}
+
+func (t *compatibilityTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	if req == nil || req.URL == nil {
+		return t.base.RoundTrip(req)
+	}
+
+	opts := GetNetworkCompatibilityOptions()
+	if !opts.AllowHTTP || req.URL.Scheme != "https" {
+		return t.base.RoundTrip(req)
+	}
+
+	// Compatibility mode should prefer HTTPS and only fallback to HTTP on
+	// transport-level failures. Forcing HTTP unconditionally can trigger
+	// redirect loops (http -> https) on providers that enforce HTTPS.
+	resp, err := t.base.RoundTrip(req)
+	if err == nil {
+		return resp, nil
+	}
+
+	if !canFallbackToHTTP(req) {
+		return nil, err
+	}
+
+	fallbackReq, cloneErr := cloneRequestWithHTTPScheme(req, "http")
+	if cloneErr != nil {
+		return nil, err
+	}
+
+	GoLog("[HTTP] HTTPS request failed for %s, retrying over HTTP: %v\n", req.URL.Host, err)
+	return t.base.RoundTrip(fallbackReq)
+}
+
+func canFallbackToHTTP(req *http.Request) bool {
+	if req == nil {
+		return false
+	}
+
+	switch strings.ToUpper(req.Method) {
+	case http.MethodGet, http.MethodHead, http.MethodOptions, http.MethodDelete:
+		return true
+	default:
+		return req.GetBody != nil
+	}
+}
+
+func cloneRequestWithHTTPScheme(req *http.Request, scheme string) (*http.Request, error) {
+	reqCopy := req.Clone(req.Context())
+	if req.Body != nil && req.GetBody != nil {
+		bodyCopy, err := req.GetBody()
+		if err != nil {
+			return nil, err
+		}
+		reqCopy.Body = bodyCopy
+	}
+
+	urlCopy := *req.URL
+	urlCopy.Scheme = scheme
+	reqCopy.URL = &urlCopy
+	return reqCopy, nil
 }
 
-// Also checks for ISP blocking on errors
 func DoRequestWithUserAgent(client *http.Client, req *http.Request) (*http.Response, error) {
 	req.Header.Set("User-Agent", getRandomUserAgent())
 	resp, err := client.Do(req)
@@ -99,7 +233,6 @@ func DoRequestWithUserAgent(client *http.Client, req *http.Request) (*http.Respo
 	return resp, err
 }
 
-// RetryConfig holds configuration for retry logic
 type RetryConfig struct {
 	MaxRetries    int
 	InitialDelay  time.Duration
@@ -116,16 +249,11 @@ func DefaultRetryConfig() RetryConfig {
 	}
 }
 
-// DoRequestWithRetry executes an HTTP request with retry logic and exponential backoff
-// Handles 429 (Too Many Requests) responses with Retry-After header
-// Also detects and logs ISP blocking
 func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConfig) (*http.Response, error) {
 	var lastErr error
 	delay := config.InitialDelay
-	requestURL := req.URL.String()
 
 	for attempt := 0; attempt <= config.MaxRetries; attempt++ {
-		// Clone request for retry (body needs to be re-readable)
 		reqCopy := req.Clone(req.Context())
 		reqCopy.Header.Set("User-Agent", getRandomUserAgent())
 
@@ -133,10 +261,8 @@ func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConf
 		if err != nil {
 			lastErr = err
 
-			// Check for ISP blocking on network errors
-			if CheckAndLogISPBlocking(err, requestURL, "HTTP") {
-				// Don't retry if ISP blocking is detected - it won't help
-				return nil, WrapErrorWithISPCheck(err, requestURL, "HTTP")
+			if CheckAndLogISPBlocking(err, reqCopy.URL.String(), "HTTP") {
+				return nil, WrapErrorWithISPCheck(err, reqCopy.URL.String(), "HTTP")
 			}
 
 			if attempt < config.MaxRetries {
@@ -148,12 +274,10 @@ func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConf
 			continue
 		}
 
-		// Success
 		if resp.StatusCode >= 200 && resp.StatusCode < 300 {
 			return resp, nil
 		}
 
-		// Handle rate limiting (429)
 		if resp.StatusCode == 429 {
 			resp.Body.Close()
 			retryAfter := getRetryAfterDuration(resp)
@@ -169,14 +293,11 @@ func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConf
 			continue
 		}
 
-		// Check for ISP blocking via HTTP status codes
-		// Some ISPs return 403 or 451 when blocking content
 		if resp.StatusCode == 403 || resp.StatusCode == 451 {
 			body, _ := io.ReadAll(resp.Body)
 			resp.Body.Close()
 			bodyStr := strings.ToLower(string(body))
 
-			// Check if response looks like ISP blocking page
 			ispBlockingIndicators := []string{
 				"blocked", "forbidden", "access denied", "not available in your",
 				"restricted", "censored", "unavailable for legal", "blocked by",
@@ -193,7 +314,6 @@ func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConf
 			}
 		}
 
-		// Server errors (5xx) - retry
 		if resp.StatusCode >= 500 {
 			resp.Body.Close()
 			lastErr = fmt.Errorf("server error: HTTP %d", resp.StatusCode)
@@ -205,7 +325,6 @@ func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConf
 			continue
 		}
 
-		// Client errors (4xx except 429) - don't retry
 		return resp, nil
 	}
 
@@ -217,19 +336,18 @@ func calculateNextDelay(currentDelay time.Duration, config RetryConfig) time.Dur
 	return min(nextDelay, config.MaxDelay)
 }
 
-// Returns 60 seconds as default if header is missing or invalid
+// Returns 0 if the header is missing or invalid so callers can keep their
+// normal exponential backoff instead of stalling for an arbitrary minute.
 func getRetryAfterDuration(resp *http.Response) time.Duration {
 	retryAfter := resp.Header.Get("Retry-After")
 	if retryAfter == "" {
-		return 60 * time.Second // Default wait time
+		return 0
 	}
 
-	// Try parsing as seconds
 	if seconds, err := strconv.Atoi(retryAfter); err == nil {
 		return time.Duration(seconds) * time.Second
 	}
 
-	// Try parsing as HTTP date
 	if t, err := http.ParseTime(retryAfter); err == nil {
 		duration := time.Until(t)
 		if duration > 0 {
@@ -237,11 +355,9 @@ func getRetryAfterDuration(resp *http.Response) time.Duration {
 		}
 	}
 
-	return 60 * time.Second // Default
+	return 0
 }
 
-// ReadResponseBody reads and returns the response body
-// Returns error if body is empty
 func ReadResponseBody(resp *http.Response) ([]byte, error) {
 	if resp == nil {
 		return nil, fmt.Errorf("response is nil")
@@ -271,14 +387,12 @@ func ValidateResponse(resp *http.Response) error {
 	return nil
 }
 
-// BuildErrorMessage creates a detailed error message for API failures
 func BuildErrorMessage(apiURL string, statusCode int, responsePreview string) string {
 	msg := fmt.Sprintf("API %s failed", apiURL)
 	if statusCode > 0 {
 		msg += fmt.Sprintf(" (HTTP %d)", statusCode)
 	}
 	if responsePreview != "" {
-		// Truncate preview if too long
 		if len(responsePreview) > 100 {
 			responsePreview = responsePreview[:100] + "..."
 		}
@@ -297,18 +411,14 @@ func (e *ISPBlockingError) Error() string {
 	return fmt.Sprintf("ISP blocking detected for %s: %s", e.Domain, e.Reason)
 }
 
-// IsISPBlocking checks if an error is likely caused by ISP blocking
-// Returns the ISPBlockingError if detected, nil otherwise
 func IsISPBlocking(err error, requestURL string) *ISPBlockingError {
 	if err == nil {
 		return nil
 	}
 
-	// Extract domain from URL
 	domain := extractDomain(requestURL)
 	errStr := strings.ToLower(err.Error())
 
-	// Check for DNS resolution failure (common ISP blocking method)
 	var dnsErr *net.DNSError
 	if errors.As(err, &dnsErr) {
 		if dnsErr.IsNotFound || dnsErr.IsTemporary {
@@ -320,11 +430,9 @@ func IsISPBlocking(err error, requestURL string) *ISPBlockingError {
 		}
 	}
 
-	// Check for connection refused (ISP firewall blocking)
 	var opErr *net.OpError
 	if errors.As(err, &opErr) {
 		if opErr.Op == "dial" {
-			// Check for specific syscall errors
 			var syscallErr syscall.Errno
 			if errors.As(opErr.Err, &syscallErr) {
 				switch syscallErr {
@@ -363,7 +471,6 @@ func IsISPBlocking(err error, requestURL string) *ISPBlockingError {
 		}
 	}
 
-	// Check for TLS handshake failure (ISP MITM or blocking HTTPS)
 	var tlsErr *tls.RecordHeaderError
 	if errors.As(err, &tlsErr) {
 		return &ISPBlockingError{
@@ -373,7 +480,6 @@ func IsISPBlocking(err error, requestURL string) *ISPBlockingError {
 		}
 	}
 
-	// Check error message patterns for common ISP blocking indicators
 	blockingPatterns := []struct {
 		pattern string
 		reason  string
@@ -402,7 +508,6 @@ func IsISPBlocking(err error, requestURL string) *ISPBlockingError {
 	return nil
 }
 
-// Returns true if ISP blocking was detected
 func CheckAndLogISPBlocking(err error, requestURL string, tag string) bool {
 	ispErr := IsISPBlocking(err, requestURL)
 	if ispErr != nil {
@@ -416,7 +521,6 @@ func CheckAndLogISPBlocking(err error, requestURL string, tag string) bool {
 	return false
 }
 
-// extractDomain extracts the domain from a URL string
 func extractDomain(rawURL string) string {
 	if rawURL == "" {
 		return "unknown"
@@ -424,7 +528,6 @@ func extractDomain(rawURL string) string {
 
 	parsed, err := url.Parse(rawURL)
 	if err != nil {
-		// Try to extract domain manually
 		rawURL = strings.TrimPrefix(rawURL, "https://")
 		rawURL = strings.TrimPrefix(rawURL, "http://")
 		if idx := strings.Index(rawURL, "/"); idx > 0 {
@@ -439,7 +542,6 @@ func extractDomain(rawURL string) string {
 	return "unknown"
 }
 
-// If ISP blocking is detected, returns a more descriptive error
 func WrapErrorWithISPCheck(err error, requestURL string, tag string) error {
 	if err == nil {
 		return nil

go_backend/httputil_ios.go

@@ -0,0 +1,20 @@
+//go:build ios
+
+package gobackend
+
+import (
+	"net/http"
+)
+
+func GetCloudflareBypassClient() *http.Client {
+	return sharedClient
+}
+
+func DoRequestWithCloudflareBypass(req *http.Request) (*http.Response, error) {
+	req.Header.Set("User-Agent", getRandomUserAgent())
+	resp, err := sharedClient.Do(req)
+	if err != nil {
+		CheckAndLogISPBlocking(err, req.URL.String(), "HTTP")
+	}
+	return resp, err
+}

go_backend/httputil_utls.go

@@ -0,0 +1,165 @@
+//go:build !ios
+
+package gobackend
+
+import (
+	"context"
+	"crypto/tls"
+	"io"
+	"net"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync"
+
+	utls "github.com/refraction-networking/utls"
+	"golang.org/x/net/http2"
+)
+
+type utlsTransport struct {
+	dialer       *net.Dialer
+	mu           sync.Mutex
+	h2Transports map[string]*http2.Transport
+}
+
+func newUTLSTransport() *utlsTransport {
+	return &utlsTransport{
+		dialer: &net.Dialer{
+			Timeout:   30 * Second,
+			KeepAlive: 30 * Second,
+		},
+		h2Transports: make(map[string]*http2.Transport),
+	}
+}
+
+func (t *utlsTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	if req.URL.Scheme != "https" {
+		return sharedTransport.RoundTrip(req)
+	}
+
+	host := req.URL.Hostname()
+	port := t.getPort(req.URL)
+	addr := net.JoinHostPort(host, port)
+
+	conn, err := t.dialer.DialContext(req.Context(), "tcp", addr)
+	if err != nil {
+		return nil, err
+	}
+
+	tlsConn := utls.UClient(conn, &utls.Config{
+		ServerName: host,
+		NextProtos: []string{"h2", "http/1.1"},
+	}, utls.HelloChrome_Auto)
+
+	if err := tlsConn.Handshake(); err != nil {
+		conn.Close()
+		return nil, err
+	}
+
+	negotiatedProto := tlsConn.ConnectionState().NegotiatedProtocol
+
+	if negotiatedProto == "h2" {
+		h2Transport := &http2.Transport{
+			DialTLSContext: func(ctx context.Context, network, addr string, cfg *tls.Config) (net.Conn, error) {
+				return tlsConn, nil
+			},
+			AllowHTTP:          false,
+			DisableCompression: false,
+		}
+		return h2Transport.RoundTrip(req)
+	}
+
+	transport := &http.Transport{
+		DialTLSContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
+			return tlsConn, nil
+		},
+		DisableKeepAlives: true,
+	}
+
+	return transport.RoundTrip(req)
+}
+
+func (t *utlsTransport) getPort(u *url.URL) string {
+	if u.Port() != "" {
+		return u.Port()
+	}
+	if u.Scheme == "https" {
+		return "443"
+	}
+	return "80"
+}
+
+var cloudflareBypassTransport = newUTLSTransport()
+
+var cloudflareBypassClient = &http.Client{
+	Transport: cloudflareBypassTransport,
+	Timeout:   DefaultTimeout,
+}
+
+func GetCloudflareBypassClient() *http.Client {
+	return cloudflareBypassClient
+}
+
+func DoRequestWithCloudflareBypass(req *http.Request) (*http.Response, error) {
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := sharedClient.Do(req)
+	if err == nil {
+		if resp.StatusCode == 403 || resp.StatusCode == 503 {
+			body, readErr := io.ReadAll(resp.Body)
+			resp.Body.Close()
+
+			if readErr == nil {
+				bodyStr := strings.ToLower(string(body))
+				cloudflareMarkers := []string{
+					"cloudflare", "cf-ray", "checking your browser",
+					"please wait", "ddos protection", "ray id",
+					"enable javascript", "challenge-platform",
+				}
+
+				isCloudflare := false
+				for _, marker := range cloudflareMarkers {
+					if strings.Contains(bodyStr, marker) {
+						isCloudflare = true
+						break
+					}
+				}
+
+				if isCloudflare {
+					LogDebug("HTTP", "Cloudflare detected, retrying with Chrome TLS fingerprint...")
+
+					reqCopy := req.Clone(req.Context())
+					reqCopy.Header.Set("User-Agent", getRandomUserAgent())
+
+					return cloudflareBypassClient.Do(reqCopy)
+				}
+			}
+
+			return &http.Response{
+				Status:     resp.Status,
+				StatusCode: resp.StatusCode,
+				Header:     resp.Header,
+				Body:       io.NopCloser(strings.NewReader(string(body))),
+			}, nil
+		}
+		return resp, nil
+	}
+
+	errStr := strings.ToLower(err.Error())
+	tlsRelated := strings.Contains(errStr, "tls") ||
+		strings.Contains(errStr, "handshake") ||
+		strings.Contains(errStr, "certificate") ||
+		strings.Contains(errStr, "connection reset")
+
+	if tlsRelated {
+		LogDebug("HTTP", "TLS error detected, retrying with Chrome TLS fingerprint: %v", err)
+
+		reqCopy := req.Clone(req.Context())
+		reqCopy.Header.Set("User-Agent", getRandomUserAgent())
+
+		return cloudflareBypassClient.Do(reqCopy)
+	}
+
+	CheckAndLogISPBlocking(err, req.URL.String(), "HTTP")
+	return nil, err
+}

go_backend/idhs.go

@@ -0,0 +1,178 @@
+package gobackend
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+)
+
+type IDHSClient struct {
+	client *http.Client
+}
+
+var (
+	globalIDHSClient *IDHSClient
+	idhsClientOnce   sync.Once
+	idhsRateLimiter  = NewRateLimiter(8, time.Minute) // 8 req/min (below 10 limit)
+)
+
+type IDHSSearchRequest struct {
+	Link     string   `json:"link"`
+	Adapters []string `json:"adapters,omitempty"`
+}
+
+type IDHSSearchResponse struct {
+	ID            string     `json:"id"`
+	Type          string     `json:"type"` // song, album, artist, podcast, show
+	Title         string     `json:"title"`
+	Description   string     `json:"description"`
+	Image         string     `json:"image,omitempty"`
+	Audio         string     `json:"audio,omitempty"`
+	Source        string     `json:"source"`
+	UniversalLink string     `json:"universalLink"`
+	Links         []IDHSLink `json:"links"`
+}
+
+type IDHSLink struct {
+	Type         string `json:"type"` // spotify, youTube, appleMusic, deezer, soundCloud, tidal
+	URL          string `json:"url"`
+	IsVerified   bool   `json:"isVerified,omitempty"`
+	NotAvailable bool   `json:"notAvailable,omitempty"`
+}
+
+func NewIDHSClient() *IDHSClient {
+	idhsClientOnce.Do(func() {
+		globalIDHSClient = &IDHSClient{
+			client: NewHTTPClientWithTimeout(15 * time.Second),
+		}
+	})
+	return globalIDHSClient
+}
+
+func (c *IDHSClient) Search(link string, adapters []string) (*IDHSSearchResponse, error) {
+	idhsRateLimiter.WaitForSlot()
+
+	reqBody := IDHSSearchRequest{
+		Link:     link,
+		Adapters: adapters,
+	}
+
+	jsonBody, err := json.Marshal(reqBody)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	req, err := http.NewRequest("POST", "https://idonthavespotify.sjdonado.com/api/search?v=1", bytes.NewBuffer(jsonBody))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode == 400 {
+		return nil, fmt.Errorf("invalid link or missing parameters")
+	}
+	if resp.StatusCode == 429 {
+		return nil, fmt.Errorf("IDHS rate limit exceeded")
+	}
+	if resp.StatusCode == 500 {
+		return nil, fmt.Errorf("IDHS processing failed")
+	}
+	if resp.StatusCode != 200 {
+		return nil, fmt.Errorf("IDHS API returned status %d", resp.StatusCode)
+	}
+
+	body, err := ReadResponseBody(resp)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+
+	var result IDHSSearchResponse
+	if err := json.Unmarshal(body, &result); err != nil {
+		return nil, fmt.Errorf("failed to decode response: %w", err)
+	}
+
+	return &result, nil
+}
+
+func (c *IDHSClient) GetAvailabilityFromSpotify(spotifyTrackID string) (*TrackAvailability, error) {
+	spotifyURL := fmt.Sprintf("https://open.spotify.com/track/%s", spotifyTrackID)
+
+	adapters := []string{"tidal", "deezer"}
+
+	result, err := c.Search(spotifyURL, adapters)
+	if err != nil {
+		return nil, err
+	}
+
+	availability := &TrackAvailability{
+		SpotifyID: spotifyTrackID,
+	}
+
+	for _, link := range result.Links {
+		if link.NotAvailable {
+			continue
+		}
+
+		switch strings.ToLower(link.Type) {
+		case "tidal":
+			availability.Tidal = true
+			availability.TidalURL = link.URL
+		case "deezer":
+			availability.Deezer = true
+			availability.DeezerURL = link.URL
+			availability.DeezerID = extractDeezerIDFromURL(link.URL)
+		}
+	}
+
+	LogDebug("IDHS", "Availability from Spotify %s: Tidal=%v, Deezer=%v",
+		spotifyTrackID, availability.Tidal, availability.Deezer)
+
+	return availability, nil
+}
+
+func (c *IDHSClient) GetAvailabilityFromDeezer(deezerTrackID string) (*TrackAvailability, error) {
+	deezerURL := fmt.Sprintf("https://www.deezer.com/track/%s", deezerTrackID)
+
+	adapters := []string{"spotify", "tidal"}
+
+	result, err := c.Search(deezerURL, adapters)
+	if err != nil {
+		return nil, err
+	}
+
+	availability := &TrackAvailability{
+		Deezer:   true,
+		DeezerID: deezerTrackID,
+	}
+
+	for _, link := range result.Links {
+		if link.NotAvailable {
+			continue
+		}
+
+		switch strings.ToLower(link.Type) {
+		case "spotify":
+			availability.SpotifyID = extractSpotifyIDFromURL(link.URL)
+		case "tidal":
+			availability.Tidal = true
+			availability.TidalURL = link.URL
+		}
+	}
+
+	LogDebug("IDHS", "Availability from Deezer %s: Spotify=%s, Tidal=%v",
+		deezerTrackID, availability.SpotifyID, availability.Tidal)
+
+	return availability, nil
+}

go_backend/library_scan.go

@@ -0,0 +1,909 @@
+package gobackend
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+type LibraryScanResult struct {
+	ID                   string `json:"id"`
+	TrackName            string `json:"trackName"`
+	ArtistName           string `json:"artistName"`
+	AlbumName            string `json:"albumName"`
+	AlbumArtist          string `json:"albumArtist,omitempty"`
+	FilePath             string `json:"filePath"`
+	CoverPath            string `json:"coverPath,omitempty"`
+	ScannedAt            string `json:"scannedAt"`
+	FileModTime          int64  `json:"fileModTime,omitempty"` // Unix timestamp in milliseconds
+	ISRC                 string `json:"isrc,omitempty"`
+	TrackNumber          int    `json:"trackNumber,omitempty"`
+	TotalTracks          int    `json:"totalTracks,omitempty"`
+	DiscNumber           int    `json:"discNumber,omitempty"`
+	TotalDiscs           int    `json:"totalDiscs,omitempty"`
+	Duration             int    `json:"duration,omitempty"`
+	ReleaseDate          string `json:"releaseDate,omitempty"`
+	BitDepth             int    `json:"bitDepth,omitempty"`
+	SampleRate           int    `json:"sampleRate,omitempty"`
+	Bitrate              int    `json:"bitrate,omitempty"` // kbps, for lossy formats (MP3, Opus, Vorbis)
+	Genre                string `json:"genre,omitempty"`
+	Composer             string `json:"composer,omitempty"`
+	Label                string `json:"label,omitempty"`
+	Copyright            string `json:"copyright,omitempty"`
+	Format               string `json:"format,omitempty"`
+	MetadataFromFilename bool   `json:"metadataFromFilename,omitempty"`
+}
+
+type LibraryScanProgress struct {
+	TotalFiles   int     `json:"total_files"`
+	ScannedFiles int     `json:"scanned_files"`
+	CurrentFile  string  `json:"current_file"`
+	ErrorCount   int     `json:"error_count"`
+	ProgressPct  float64 `json:"progress_pct"`
+	IsComplete   bool    `json:"is_complete"`
+}
+
+type IncrementalScanResult struct {
+	Scanned      []LibraryScanResult `json:"scanned"`      // New or updated files
+	DeletedPaths []string            `json:"deletedPaths"` // Files that no longer exist
+	SkippedCount int                 `json:"skippedCount"` // Files that were unchanged
+	TotalFiles   int                 `json:"totalFiles"`   // Total files in folder
+}
+
+var (
+	libraryScanProgress   LibraryScanProgress
+	libraryScanProgressMu sync.RWMutex
+	libraryScanCancel     chan struct{}
+	libraryScanCancelMu   sync.Mutex
+	libraryCoverCacheDir  string
+	libraryCoverCacheMu   sync.RWMutex
+)
+
+var supportedAudioFormats = map[string]bool{
+	".flac": true,
+	".m4a":  true,
+	".mp3":  true,
+	".opus": true,
+	".ogg":  true,
+	".ape":  true,
+	".wv":   true,
+	".mpc":  true,
+	".cue":  true,
+}
+
+type libraryAudioFileInfo struct {
+	path    string
+	modTime int64
+}
+
+type scannedCueFileInfo struct {
+	sheet     *CueSheet
+	audioPath string
+}
+
+func collectLibraryAudioFiles(folderPath string, cancelCh <-chan struct{}) ([]libraryAudioFileInfo, error) {
+	var files []libraryAudioFileInfo
+
+	err := filepath.Walk(folderPath, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return nil
+		}
+
+		select {
+		case <-cancelCh:
+			return fmt.Errorf("scan cancelled")
+		default:
+		}
+
+		if info.IsDir() {
+			return nil
+		}
+
+		ext := strings.ToLower(filepath.Ext(path))
+		if !supportedAudioFormats[ext] {
+			return nil
+		}
+
+		files = append(files, libraryAudioFileInfo{
+			path:    path,
+			modTime: info.ModTime().UnixMilli(),
+		})
+		return nil
+	})
+
+	if err != nil {
+		return nil, err
+	}
+
+	return files, nil
+}
+
+func SetLibraryCoverCacheDir(cacheDir string) {
+	libraryCoverCacheMu.Lock()
+	libraryCoverCacheDir = cacheDir
+	libraryCoverCacheMu.Unlock()
+}
+
+func ScanLibraryFolder(folderPath string) (string, error) {
+	if folderPath == "" {
+		return "[]", fmt.Errorf("folder path is empty")
+	}
+
+	info, err := os.Stat(folderPath)
+	if err != nil {
+		return "[]", fmt.Errorf("folder not found: %w", err)
+	}
+	if !info.IsDir() {
+		return "[]", fmt.Errorf("path is not a folder: %s", folderPath)
+	}
+
+	libraryScanProgressMu.Lock()
+	libraryScanProgress = LibraryScanProgress{}
+	libraryScanProgressMu.Unlock()
+
+	libraryScanCancelMu.Lock()
+	if libraryScanCancel != nil {
+		close(libraryScanCancel)
+	}
+	libraryScanCancel = make(chan struct{})
+	cancelCh := libraryScanCancel
+	libraryScanCancelMu.Unlock()
+
+	audioFileInfos, err := collectLibraryAudioFiles(folderPath, cancelCh)
+	if err != nil {
+		return "[]", err
+	}
+
+	totalFiles := len(audioFileInfos)
+	libraryScanProgressMu.Lock()
+	libraryScanProgress.TotalFiles = totalFiles
+	libraryScanProgressMu.Unlock()
+
+	if totalFiles == 0 {
+		libraryScanProgressMu.Lock()
+		libraryScanProgress.IsComplete = true
+		libraryScanProgressMu.Unlock()
+		return "[]", nil
+	}
+
+	GoLog("[LibraryScan] Found %d audio files to scan\n", totalFiles)
+
+	results := make([]LibraryScanResult, 0, totalFiles)
+	scanTime := time.Now().UTC().Format(time.RFC3339)
+	errorCount := 0
+
+	cueReferencedAudioFiles := make(map[string]bool)
+	parsedCueFiles := make(map[string]scannedCueFileInfo)
+
+	for _, fileInfo := range audioFileInfos {
+		filePath := fileInfo.path
+		ext := strings.ToLower(filepath.Ext(filePath))
+		if ext == ".cue" {
+			sheet, err := ParseCueFile(filePath)
+			if err == nil && sheet.FileName != "" {
+				audioPath := ResolveCueAudioPath(filePath, sheet.FileName)
+				if audioPath != "" {
+					parsedCueFiles[filePath] = scannedCueFileInfo{
+						sheet:     sheet,
+						audioPath: audioPath,
+					}
+					cueReferencedAudioFiles[audioPath] = true
+				}
+			}
+		}
+	}
+
+	for i, fileInfo := range audioFileInfos {
+		filePath := fileInfo.path
+		select {
+		case <-cancelCh:
+			return "[]", fmt.Errorf("scan cancelled")
+		default:
+		}
+
+		libraryScanProgressMu.Lock()
+		libraryScanProgress.ScannedFiles = i + 1
+		libraryScanProgress.CurrentFile = filepath.Base(filePath)
+		libraryScanProgress.ProgressPct = float64(i+1) / float64(totalFiles) * 100
+		libraryScanProgressMu.Unlock()
+
+		ext := strings.ToLower(filepath.Ext(filePath))
+
+		if ext == ".cue" {
+			var cueResults []LibraryScanResult
+			cueInfo, ok := parsedCueFiles[filePath]
+			if ok {
+				cueResults, err = scanCueSheetForLibrary(
+					filePath,
+					cueInfo.sheet,
+					cueInfo.audioPath,
+					"",
+					fileInfo.modTime,
+					"",
+					scanTime,
+				)
+			} else {
+				cueResults, err = ScanCueFileForLibrary(filePath, scanTime)
+			}
+			if err != nil {
+				errorCount++
+				GoLog("[LibraryScan] Error scanning cue %s: %v\n", filePath, err)
+				continue
+			}
+			results = append(results, cueResults...)
+			GoLog("[LibraryScan] CUE sheet %s: %d tracks\n", filepath.Base(filePath), len(cueResults))
+			continue
+		}
+
+		if cueReferencedAudioFiles[filePath] {
+			GoLog("[LibraryScan] Skipping %s (referenced by .cue sheet)\n", filepath.Base(filePath))
+			continue
+		}
+
+		result, err := scanAudioFileWithKnownModTime(filePath, scanTime, fileInfo.modTime)
+		if err != nil {
+			errorCount++
+			GoLog("[LibraryScan] Error scanning %s: %v\n", filePath, err)
+			continue
+		}
+
+		results = append(results, *result)
+	}
+
+	libraryScanProgressMu.Lock()
+	libraryScanProgress.ErrorCount = errorCount
+	libraryScanProgress.IsComplete = true
+	libraryScanProgressMu.Unlock()
+
+	GoLog("[LibraryScan] Scan complete: %d tracks found, %d errors\n", len(results), errorCount)
+
+	jsonBytes, err := json.Marshal(results)
+	if err != nil {
+		return "[]", fmt.Errorf("failed to marshal results: %w", err)
+	}
+
+	return string(jsonBytes), nil
+}
+
+func scanAudioFile(filePath, scanTime string) (*LibraryScanResult, error) {
+	return scanAudioFileWithKnownModTimeAndDisplayName(filePath, "", scanTime, 0)
+}
+
+func scanAudioFileWithKnownModTime(filePath, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
+	return scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(filePath, "", "", scanTime, knownModTime)
+}
+
+func scanAudioFileWithKnownModTimeAndDisplayName(filePath, displayNameHint, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
+	return scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(filePath, displayNameHint, "", scanTime, knownModTime)
+}
+
+func scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(filePath, displayNameHint, coverCacheKey, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
+	ext := resolveLibraryAudioExt(filePath, displayNameHint)
+
+	result := &LibraryScanResult{
+		ID:        generateLibraryID(filePath),
+		FilePath:  filePath,
+		ScannedAt: scanTime,
+		Format:    strings.TrimPrefix(ext, "."),
+	}
+
+	if knownModTime > 0 {
+		result.FileModTime = knownModTime
+	} else if info, err := os.Stat(filePath); err == nil {
+		result.FileModTime = info.ModTime().UnixMilli()
+	}
+
+	libraryCoverCacheMu.RLock()
+	coverCacheDir := libraryCoverCacheDir
+	libraryCoverCacheMu.RUnlock()
+	if coverCacheDir != "" {
+		coverPath, err := SaveCoverToCacheWithHintAndKey(
+			filePath,
+			displayNameHint,
+			coverCacheDir,
+			coverCacheKey,
+		)
+		if err == nil && coverPath != "" {
+			result.CoverPath = coverPath
+		}
+	}
+
+	switch ext {
+	case ".flac":
+		return scanFLACFile(filePath, result, displayNameHint)
+	case ".m4a":
+		return scanM4AFile(filePath, result, displayNameHint)
+	case ".mp3":
+		return scanMP3File(filePath, result, displayNameHint)
+	case ".opus", ".ogg":
+		return scanOggFile(filePath, result, displayNameHint)
+	case ".ape", ".wv", ".mpc":
+		return scanAPEFile(filePath, result, displayNameHint)
+	default:
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+}
+
+func resolveLibraryAudioExt(filePath, displayNameHint string) string {
+	ext := strings.ToLower(filepath.Ext(filePath))
+	if ext != "" {
+		return ext
+	}
+	return strings.ToLower(filepath.Ext(displayNameHint))
+}
+
+func libraryDisplayNameOrPath(filePath, displayNameHint string) string {
+	if displayNameHint != "" {
+		return displayNameHint
+	}
+	return filePath
+}
+
+func applyDefaultLibraryMetadata(filePath, displayNameHint string, result *LibraryScanResult) {
+	nameSource := libraryDisplayNameOrPath(filePath, displayNameHint)
+	if result.TrackName == "" {
+		result.TrackName = strings.TrimSuffix(filepath.Base(nameSource), filepath.Ext(nameSource))
+	}
+	if result.ArtistName == "" {
+		result.ArtistName = "Unknown Artist"
+	}
+	if result.AlbumName == "" {
+		result.AlbumName = "Unknown Album"
+	}
+}
+
+func scanFLACFile(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
+	metadata, err := ReadMetadata(filePath)
+	if err != nil {
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+
+	result.TrackName = metadata.Title
+	result.ArtistName = metadata.Artist
+	result.AlbumName = metadata.Album
+	result.AlbumArtist = metadata.AlbumArtist
+	result.ISRC = metadata.ISRC
+	result.TrackNumber = metadata.TrackNumber
+	result.TotalTracks = metadata.TotalTracks
+	result.DiscNumber = metadata.DiscNumber
+	result.TotalDiscs = metadata.TotalDiscs
+	result.ReleaseDate = metadata.Date
+	result.Genre = metadata.Genre
+	result.Composer = metadata.Composer
+	result.Label = metadata.Label
+	result.Copyright = metadata.Copyright
+
+	quality, err := GetAudioQuality(filePath)
+	if err == nil {
+		result.BitDepth = quality.BitDepth
+		result.SampleRate = quality.SampleRate
+		if quality.SampleRate > 0 && quality.TotalSamples > 0 {
+			result.Duration = int(quality.TotalSamples / int64(quality.SampleRate))
+		}
+	}
+
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
+
+	return result, nil
+}
+
+func scanM4AFile(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
+	metadata, err := ReadM4ATags(filePath)
+	if err != nil {
+		GoLog("[LibraryScan] M4A read error for %s: %v\n", filePath, err)
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+
+	if metadata != nil {
+		result.TrackName = metadata.Title
+		result.ArtistName = metadata.Artist
+		result.AlbumName = metadata.Album
+		result.AlbumArtist = metadata.AlbumArtist
+		result.ISRC = metadata.ISRC
+		result.TrackNumber = metadata.TrackNumber
+		result.TotalTracks = metadata.TotalTracks
+		result.DiscNumber = metadata.DiscNumber
+		result.TotalDiscs = metadata.TotalDiscs
+		result.ReleaseDate = metadata.Date
+		if result.ReleaseDate == "" {
+			result.ReleaseDate = metadata.Year
+		}
+		result.Genre = metadata.Genre
+		result.Composer = metadata.Composer
+		result.Label = metadata.Label
+		result.Copyright = metadata.Copyright
+	}
+
+	quality, err := GetM4AQuality(filePath)
+	if err == nil {
+		result.BitDepth = quality.BitDepth
+		result.SampleRate = quality.SampleRate
+	}
+
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
+	return result, nil
+}
+
+func scanMP3File(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
+	metadata, err := ReadID3Tags(filePath)
+	if err != nil {
+		GoLog("[LibraryScan] ID3 read error for %s: %v\n", filePath, err)
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+
+	result.TrackName = metadata.Title
+	result.ArtistName = metadata.Artist
+	result.AlbumName = metadata.Album
+	result.AlbumArtist = metadata.AlbumArtist
+	result.TrackNumber = metadata.TrackNumber
+	result.TotalTracks = metadata.TotalTracks
+	result.DiscNumber = metadata.DiscNumber
+	result.TotalDiscs = metadata.TotalDiscs
+	result.Genre = metadata.Genre
+	if metadata.Date != "" {
+		result.ReleaseDate = metadata.Date
+	} else {
+		result.ReleaseDate = metadata.Year
+	}
+	result.ISRC = metadata.ISRC
+	result.Composer = metadata.Composer
+	result.Label = metadata.Label
+	result.Copyright = metadata.Copyright
+
+	quality, err := GetMP3Quality(filePath)
+	if err == nil {
+		result.SampleRate = quality.SampleRate
+		result.BitDepth = quality.BitDepth // 0 for lossy
+		result.Duration = quality.Duration
+		if quality.Bitrate > 0 {
+			result.Bitrate = quality.Bitrate / 1000 // convert bps to kbps
+		}
+	}
+
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
+
+	return result, nil
+}
+
+func scanOggFile(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
+	metadata, err := ReadOggVorbisComments(filePath)
+	if err != nil {
+		GoLog("[LibraryScan] Ogg/Opus read error for %s: %v\n", filePath, err)
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+
+	result.TrackName = metadata.Title
+	result.ArtistName = metadata.Artist
+	result.AlbumName = metadata.Album
+	result.AlbumArtist = metadata.AlbumArtist
+	result.ISRC = metadata.ISRC
+	result.TrackNumber = metadata.TrackNumber
+	result.TotalTracks = metadata.TotalTracks
+	result.DiscNumber = metadata.DiscNumber
+	result.TotalDiscs = metadata.TotalDiscs
+	result.Genre = metadata.Genre
+	result.ReleaseDate = metadata.Date
+	result.Composer = metadata.Composer
+	result.Label = metadata.Label
+	result.Copyright = metadata.Copyright
+
+	quality, err := GetOggQuality(filePath)
+	if err == nil {
+		result.SampleRate = quality.SampleRate
+		result.BitDepth = quality.BitDepth // 0 for lossy
+		result.Duration = quality.Duration
+		if quality.Bitrate > 0 {
+			result.Bitrate = quality.Bitrate / 1000 // convert bps to kbps
+		}
+	}
+
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
+
+	return result, nil
+}
+
+func scanAPEFile(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
+	tag, err := ReadAPETags(filePath)
+	if err != nil {
+		GoLog("[LibraryScan] APE tag read error for %s: %v\n", filePath, err)
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+
+	metadata := APETagToAudioMetadata(tag)
+	if metadata == nil {
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+
+	result.TrackName = metadata.Title
+	result.ArtistName = metadata.Artist
+	result.AlbumName = metadata.Album
+	result.AlbumArtist = metadata.AlbumArtist
+	result.ISRC = metadata.ISRC
+	result.TrackNumber = metadata.TrackNumber
+	result.TotalTracks = metadata.TotalTracks
+	result.DiscNumber = metadata.DiscNumber
+	result.TotalDiscs = metadata.TotalDiscs
+	result.Genre = metadata.Genre
+	if metadata.Date != "" {
+		result.ReleaseDate = metadata.Date
+	} else {
+		result.ReleaseDate = metadata.Year
+	}
+	result.Composer = metadata.Composer
+	result.Label = metadata.Label
+	result.Copyright = metadata.Copyright
+
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
+
+	return result, nil
+}
+
+func scanFromFilename(filePath, displayNameHint string, result *LibraryScanResult) (*LibraryScanResult, error) {
+	result.MetadataFromFilename = true
+	nameSource := libraryDisplayNameOrPath(filePath, displayNameHint)
+	filename := strings.TrimSuffix(filepath.Base(nameSource), filepath.Ext(nameSource))
+
+	parts := strings.SplitN(filename, " - ", 2)
+	if len(parts) == 2 {
+		if len(parts[0]) <= 3 && isNumeric(parts[0]) {
+			result.TrackName = parts[1]
+			result.ArtistName = "Unknown Artist"
+		} else {
+			result.ArtistName = parts[0]
+			result.TrackName = parts[1]
+		}
+	} else {
+		if len(filename) > 3 && isNumeric(filename[:2]) {
+			title := strings.TrimLeft(filename[2:], " .-")
+			result.TrackName = title
+		} else {
+			result.TrackName = filename
+		}
+		result.ArtistName = "Unknown Artist"
+	}
+
+	dir := filepath.Dir(filePath)
+	result.AlbumName = filepath.Base(dir)
+	if result.AlbumName == "." || result.AlbumName == "" || result.AlbumName == "fd" || result.AlbumName == "self" {
+		result.AlbumName = "Unknown Album"
+	}
+
+	return result, nil
+}
+
+func isNumeric(s string) bool {
+	for _, c := range s {
+		if c < '0' || c > '9' {
+			return false
+		}
+	}
+	return len(s) > 0
+}
+
+func generateLibraryID(filePath string) string {
+	return fmt.Sprintf("lib_%x", hashString(filePath))
+}
+
+func hashString(s string) uint32 {
+	var hash uint32 = 5381
+	for _, c := range s {
+		hash = ((hash << 5) + hash) + uint32(c)
+	}
+	return hash
+}
+
+func GetLibraryScanProgress() string {
+	libraryScanProgressMu.RLock()
+	defer libraryScanProgressMu.RUnlock()
+
+	jsonBytes, _ := json.Marshal(libraryScanProgress)
+	return string(jsonBytes)
+}
+
+func CancelLibraryScan() {
+	libraryScanCancelMu.Lock()
+	defer libraryScanCancelMu.Unlock()
+
+	if libraryScanCancel != nil {
+		close(libraryScanCancel)
+		libraryScanCancel = nil
+	}
+}
+
+func ReadAudioMetadata(filePath string) (string, error) {
+	return ReadAudioMetadataWithDisplayName(filePath, "")
+}
+
+func ReadAudioMetadataWithDisplayName(filePath, displayNameHint string) (string, error) {
+	return ReadAudioMetadataWithDisplayNameAndCoverCacheKey(filePath, displayNameHint, "")
+}
+
+func ReadAudioMetadataWithDisplayNameAndCoverCacheKey(filePath, displayNameHint, coverCacheKey string) (string, error) {
+	scanTime := time.Now().UTC().Format(time.RFC3339)
+	result, err := scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(
+		filePath,
+		displayNameHint,
+		coverCacheKey,
+		scanTime,
+		0,
+	)
+	if err != nil {
+		return "", err
+	}
+
+	jsonBytes, err := json.Marshal(result)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal result: %w", err)
+	}
+
+	return string(jsonBytes), nil
+}
+
+func loadExistingFilesSnapshot(snapshotPath string) (map[string]int64, error) {
+	existingFiles := make(map[string]int64)
+	if snapshotPath == "" {
+		return existingFiles, nil
+	}
+
+	file, err := os.Open(snapshotPath)
+	if err != nil {
+		return nil, err
+	}
+	defer file.Close()
+
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		line := scanner.Text()
+		if line == "" {
+			continue
+		}
+		parts := strings.SplitN(line, "\t", 2)
+		if len(parts) != 2 {
+			continue
+		}
+		modTime, err := strconv.ParseInt(parts[0], 10, 64)
+		if err != nil {
+			continue
+		}
+		existingFiles[parts[1]] = modTime
+	}
+
+	if err := scanner.Err(); err != nil {
+		return nil, err
+	}
+
+	return existingFiles, nil
+}
+
+func scanLibraryFolderIncrementalWithExistingFiles(folderPath string, existingFiles map[string]int64) (string, error) {
+	if folderPath == "" {
+		return "{}", fmt.Errorf("folder path is empty")
+	}
+
+	info, err := os.Stat(folderPath)
+	if err != nil {
+		return "{}", fmt.Errorf("folder not found: %w", err)
+	}
+	if !info.IsDir() {
+		return "{}", fmt.Errorf("path is not a folder: %s", folderPath)
+	}
+
+	GoLog("[LibraryScan] Incremental scan starting, %d existing files in database\n", len(existingFiles))
+
+	libraryScanProgressMu.Lock()
+	libraryScanProgress = LibraryScanProgress{}
+	libraryScanProgressMu.Unlock()
+
+	libraryScanCancelMu.Lock()
+	if libraryScanCancel != nil {
+		close(libraryScanCancel)
+	}
+	libraryScanCancel = make(chan struct{})
+	cancelCh := libraryScanCancel
+	libraryScanCancelMu.Unlock()
+
+	currentFiles, err := collectLibraryAudioFiles(folderPath, cancelCh)
+	if err != nil {
+		return "{}", err
+	}
+	currentPathSet := make(map[string]bool, len(currentFiles))
+	for _, fileInfo := range currentFiles {
+		currentPathSet[fileInfo.path] = true
+	}
+
+	totalFiles := len(currentFiles)
+	libraryScanProgressMu.Lock()
+	libraryScanProgress.TotalFiles = totalFiles
+	libraryScanProgressMu.Unlock()
+
+	var filesToScan []libraryAudioFileInfo
+	skippedCount := 0
+	existingCueTrackModTimes := make(map[string]int64)
+	for existingPath, modTime := range existingFiles {
+		if idx := strings.LastIndex(existingPath, "#track"); idx > 0 {
+			baseCuePath := existingPath[:idx]
+			if _, exists := existingCueTrackModTimes[baseCuePath]; !exists {
+				existingCueTrackModTimes[baseCuePath] = modTime
+			}
+		}
+	}
+
+	for _, f := range currentFiles {
+		existingModTime, exists := existingFiles[f.path]
+		if !exists {
+			if strings.ToLower(filepath.Ext(f.path)) == ".cue" {
+				if cueTrackModTime, hasCueTracks := existingCueTrackModTimes[f.path]; hasCueTracks {
+					if f.modTime == cueTrackModTime {
+						skippedCount++
+					} else {
+						filesToScan = append(filesToScan, f)
+					}
+					continue
+				}
+			}
+			filesToScan = append(filesToScan, f)
+		} else if f.modTime != existingModTime {
+			filesToScan = append(filesToScan, f)
+		} else {
+			skippedCount++
+		}
+	}
+
+	var deletedPaths []string
+	for existingPath := range existingFiles {
+		if idx := strings.LastIndex(existingPath, "#track"); idx > 0 {
+			baseCuePath := existingPath[:idx]
+			if currentPathSet[baseCuePath] {
+				continue
+			}
+			deletedPaths = append(deletedPaths, existingPath)
+		} else if !currentPathSet[existingPath] {
+			deletedPaths = append(deletedPaths, existingPath)
+		}
+	}
+
+	GoLog("[LibraryScan] Incremental: %d to scan, %d skipped, %d deleted\n",
+		len(filesToScan), skippedCount, len(deletedPaths))
+
+	if len(filesToScan) == 0 {
+		libraryScanProgressMu.Lock()
+		libraryScanProgress.ScannedFiles = totalFiles
+		libraryScanProgress.IsComplete = true
+		libraryScanProgress.ProgressPct = 100
+		libraryScanProgressMu.Unlock()
+
+		result := IncrementalScanResult{
+			Scanned:      []LibraryScanResult{},
+			DeletedPaths: deletedPaths,
+			SkippedCount: skippedCount,
+			TotalFiles:   totalFiles,
+		}
+		jsonBytes, _ := json.Marshal(result)
+		return string(jsonBytes), nil
+	}
+
+	results := make([]LibraryScanResult, 0, len(filesToScan))
+	scanTime := time.Now().UTC().Format(time.RFC3339)
+	errorCount := 0
+
+	cueReferencedAudioFilesInc := make(map[string]bool)
+	parsedCueFiles := make(map[string]scannedCueFileInfo)
+	for _, f := range filesToScan {
+		ext := strings.ToLower(filepath.Ext(f.path))
+		if ext == ".cue" {
+			sheet, err := ParseCueFile(f.path)
+			if err == nil && sheet.FileName != "" {
+				audioPath := ResolveCueAudioPath(f.path, sheet.FileName)
+				if audioPath != "" {
+					parsedCueFiles[f.path] = scannedCueFileInfo{
+						sheet:     sheet,
+						audioPath: audioPath,
+					}
+					cueReferencedAudioFilesInc[audioPath] = true
+				}
+			}
+		}
+	}
+
+	for i, f := range filesToScan {
+		select {
+		case <-cancelCh:
+			return "{}", fmt.Errorf("scan cancelled")
+		default:
+		}
+
+		libraryScanProgressMu.Lock()
+		libraryScanProgress.ScannedFiles = skippedCount + i + 1
+		libraryScanProgress.CurrentFile = filepath.Base(f.path)
+		libraryScanProgress.ProgressPct = float64(skippedCount+i+1) / float64(totalFiles) * 100
+		libraryScanProgressMu.Unlock()
+
+		ext := strings.ToLower(filepath.Ext(f.path))
+
+		if ext == ".cue" {
+			var cueResults []LibraryScanResult
+			cueInfo, ok := parsedCueFiles[f.path]
+			if ok {
+				cueResults, err = scanCueSheetForLibrary(
+					f.path,
+					cueInfo.sheet,
+					cueInfo.audioPath,
+					"",
+					f.modTime,
+					"",
+					scanTime,
+				)
+			} else {
+				cueResults, err = ScanCueFileForLibrary(f.path, scanTime)
+			}
+			if err != nil {
+				errorCount++
+				GoLog("[LibraryScan] Error scanning cue %s: %v\n", f.path, err)
+				continue
+			}
+			results = append(results, cueResults...)
+			continue
+		}
+
+		if cueReferencedAudioFilesInc[f.path] {
+			continue
+		}
+
+		result, err := scanAudioFileWithKnownModTime(f.path, scanTime, f.modTime)
+		if err != nil {
+			errorCount++
+			GoLog("[LibraryScan] Error scanning %s: %v\n", f.path, err)
+			continue
+		}
+
+		results = append(results, *result)
+	}
+
+	libraryScanProgressMu.Lock()
+	libraryScanProgress.ErrorCount = errorCount
+	libraryScanProgress.IsComplete = true
+	libraryScanProgress.ScannedFiles = totalFiles
+	libraryScanProgress.ProgressPct = 100
+	libraryScanProgressMu.Unlock()
+
+	GoLog("[LibraryScan] Incremental scan complete: %d scanned, %d skipped, %d deleted, %d errors\n",
+		len(results), skippedCount, len(deletedPaths), errorCount)
+
+	scanResult := IncrementalScanResult{
+		Scanned:      results,
+		DeletedPaths: deletedPaths,
+		SkippedCount: skippedCount,
+		TotalFiles:   totalFiles,
+	}
+
+	jsonBytes, err := json.Marshal(scanResult)
+	if err != nil {
+		return "{}", fmt.Errorf("failed to marshal results: %w", err)
+	}
+
+	return string(jsonBytes), nil
+}
+
+func ScanLibraryFolderIncremental(folderPath, existingFilesJSON string) (string, error) {
+	existingFiles := make(map[string]int64)
+	if existingFilesJSON != "" && existingFilesJSON != "{}" {
+		if err := json.Unmarshal([]byte(existingFilesJSON), &existingFiles); err != nil {
+			GoLog("[LibraryScan] Warning: failed to parse existing files JSON: %v\n", err)
+		}
+	}
+	return scanLibraryFolderIncrementalWithExistingFiles(folderPath, existingFiles)
+}
+
+func ScanLibraryFolderIncrementalFromSnapshot(folderPath, snapshotPath string) (string, error) {
+	existingFiles, err := loadExistingFilesSnapshot(snapshotPath)
+	if err != nil {
+		return "{}", fmt.Errorf("failed to load incremental snapshot: %w", err)
+	}
+	return scanLibraryFolderIncrementalWithExistingFiles(folderPath, existingFiles)
+}

go_backend/library_scan_test.go

@@ -0,0 +1,25 @@
+package gobackend
+
+import "testing"
+
+func TestScanFromFilenameMarksMetadataFallback(t *testing.T) {
+	result := &LibraryScanResult{}
+
+	scanned, err := scanFromFilename(
+		"/proc/self/fd/209",
+		"189.mp3",
+		result,
+	)
+	if err != nil {
+		t.Fatalf("scanFromFilename returned error: %v", err)
+	}
+	if !scanned.MetadataFromFilename {
+		t.Fatal("expected filename fallback marker to be set")
+	}
+	if scanned.TrackName != "189" {
+		t.Fatalf("unexpected track name: %q", scanned.TrackName)
+	}
+	if scanned.ArtistName != "Unknown Artist" {
+		t.Fatalf("unexpected artist name: %q", scanned.ArtistName)
+	}
+}

go_backend/logbuffer.go

@@ -3,6 +3,7 @@ package gobackend
 import (
 	"encoding/json"
 	"fmt"
+	"regexp"
 	"strings"
 	"sync"
 	"time"
@@ -22,18 +23,35 @@ type LogBuffer struct {
 	loggingEnabled bool
 }
 
+const (
+	defaultLogBufferSize = 500
+)
+
 var (
 	globalLogBuffer *LogBuffer
 	logBufferOnce   sync.Once
+
+	authorizationBearerPattern = regexp.MustCompile(`(?i)\bAuthorization\b\s*[:=]\s*Bearer\s+[A-Za-z0-9._~+/\-]+=*`)
+	genericKeyValuePattern     = regexp.MustCompile(`(?i)\b(access[_\s-]?token|refresh[_\s-]?token|id[_\s-]?token|client[_\s-]?secret|authorization|password|api[_\s-]?key)\b(\s*[:=]\s*)([^\s,;]+)`)
+	queryTokenPattern          = regexp.MustCompile(`(?i)([?&](?:access_token|refresh_token|id_token|token|client_secret|api_key|apikey|password)=)[^&\s]+`)
+	bearerTokenPattern         = regexp.MustCompile(`(?i)\bBearer\s+[A-Za-z0-9._~+/\-]+=*`)
 )
 
-// GetLogBuffer returns the singleton log buffer instance
+func sanitizeSensitiveLogText(message string) string {
+	redacted := message
+	redacted = authorizationBearerPattern.ReplaceAllString(redacted, "Authorization: Bearer [REDACTED]")
+	redacted = genericKeyValuePattern.ReplaceAllString(redacted, `${1}${2}[REDACTED]`)
+	redacted = queryTokenPattern.ReplaceAllString(redacted, `${1}[REDACTED]`)
+	redacted = bearerTokenPattern.ReplaceAllString(redacted, "Bearer [REDACTED]")
+	return redacted
+}
+
 func GetLogBuffer() *LogBuffer {
 	logBufferOnce.Do(func() {
 		globalLogBuffer = &LogBuffer{
-			entries:        make([]LogEntry, 0, 1000),
-			maxSize:        1000,
-			loggingEnabled: false, // Default: disabled for performance (user can enable in settings)
+			entries:        make([]LogEntry, 0, defaultLogBufferSize),
+			maxSize:        defaultLogBufferSize,
+			loggingEnabled: false,
 		}
 	})
 	return globalLogBuffer
@@ -45,7 +63,6 @@ func (lb *LogBuffer) SetLoggingEnabled(enabled bool) {
 	lb.loggingEnabled = enabled
 }
 
-// IsLoggingEnabled returns whether logging is enabled
 func (lb *LogBuffer) IsLoggingEnabled() bool {
 	lb.mu.RLock()
 	defer lb.mu.RUnlock()
@@ -60,6 +77,8 @@ func (lb *LogBuffer) Add(level, tag, message string) {
 		return
 	}
 
+	message = sanitizeSensitiveLogText(message)
+
 	entry := LogEntry{
 		Timestamp: time.Now().Format("15:04:05.000"),
 		Level:     level,
@@ -75,7 +94,6 @@ func (lb *LogBuffer) Add(level, tag, message string) {
 	fmt.Printf("[%s] %s\n", tag, message)
 }
 
-// GetAll returns all log entries as JSON
 func (lb *LogBuffer) GetAll() string {
 	lb.mu.RLock()
 	defer lb.mu.RUnlock()
@@ -99,21 +117,18 @@ func (lb *LogBuffer) getSince(index int) ([]LogEntry, int) {
 	return entries, len(lb.entries)
 }
 
-// Clear clears all log entries
 func (lb *LogBuffer) Clear() {
 	lb.mu.Lock()
 	defer lb.mu.Unlock()
 	lb.entries = lb.entries[:0]
 }
 
-// Count returns the number of log entries
 func (lb *LogBuffer) Count() int {
 	lb.mu.RLock()
 	defer lb.mu.RUnlock()
 	return len(lb.entries)
 }
 
-// Helper functions for logging with different levels
 func LogDebug(tag, format string, args ...interface{}) {
 	GetLogBuffer().Add("DEBUG", tag, fmt.Sprintf(format, args...))
 }
@@ -130,13 +145,10 @@ func LogError(tag, format string, args ...interface{}) {
 	GetLogBuffer().Add("ERROR", tag, fmt.Sprintf(format, args...))
 }
 
-// GoLog is a drop-in replacement for fmt.Printf that also logs to buffer
-// It parses the tag from the format string if it starts with [Tag]
 func GoLog(format string, args ...interface{}) {
 	message := fmt.Sprintf(format, args...)
 	message = strings.TrimSuffix(message, "\n")
 
-	// Extract tag from message if present (e.g., "[Tidal] message")
 	tag := "Go"
 	level := "INFO"
 
@@ -148,13 +160,12 @@ func GoLog(format string, args ...interface{}) {
 		}
 	}
 
-	// Determine level from message content
 	msgLower := strings.ToLower(message)
-	if strings.Contains(msgLower, "error") || strings.Contains(msgLower, "failed") || strings.HasPrefix(message, "✗") {
+	if strings.Contains(msgLower, "error") || strings.Contains(msgLower, "failed") {
 		level = "ERROR"
 	} else if strings.Contains(msgLower, "warning") || strings.Contains(msgLower, "warn") {
 		level = "WARN"
-	} else if strings.HasPrefix(message, "✓") || strings.Contains(msgLower, "success") || strings.Contains(msgLower, "match found") {
+	} else if strings.Contains(msgLower, "success") || strings.Contains(msgLower, "match found") {
 		level = "INFO"
 	} else if strings.Contains(msgLower, "searching") || strings.Contains(msgLower, "trying") || strings.Contains(msgLower, "found") {
 		level = "DEBUG"
@@ -163,15 +174,10 @@ func GoLog(format string, args ...interface{}) {
 	GetLogBuffer().Add(level, tag, message)
 }
 
-// Exported functions for Flutter
-
-// GetLogs returns all logs as JSON array
 func GetLogs() string {
 	return GetLogBuffer().GetAll()
 }
 
-// GetLogsSince returns logs since the given index
-// Returns JSON: {"logs": [...], "next_index": N}
 func GetLogsSince(index int) string {
 	entries, nextIndex := GetLogBuffer().getSince(index)
 	logsJson, _ := json.Marshal(entries)
@@ -179,17 +185,14 @@ func GetLogsSince(index int) string {
 	return result
 }
 
-// ClearLogs clears all logs
 func ClearLogs() {
 	GetLogBuffer().Clear()
 }
 
-// GetLogCount returns the number of log entries
 func GetLogCount() int {
 	return GetLogBuffer().Count()
 }
 
-// SetLoggingEnabled enables or disables logging from Flutter
 func SetLoggingEnabled(enabled bool) {
 	GetLogBuffer().SetLoggingEnabled(enabled)
 }

go_backend/lyrics.go

@@ -20,6 +20,128 @@ const (
 	durationToleranceSec = 10.0
 )
 
+const (
+	LyricsProviderLRCLIB     = "lrclib"
+	LyricsProviderNetease    = "netease"
+	LyricsProviderMusixmatch = "musixmatch"
+	LyricsProviderAppleMusic = "apple_music"
+	LyricsProviderQQMusic    = "qqmusic"
+)
+
+var DefaultLyricsProviders = []string{
+	LyricsProviderLRCLIB,
+	LyricsProviderMusixmatch,
+	LyricsProviderNetease,
+	LyricsProviderAppleMusic,
+	LyricsProviderQQMusic,
+}
+
+var (
+	lyricsProvidersMu sync.RWMutex
+	lyricsProviders   []string // ordered list of enabled providers
+)
+
+type LyricsFetchOptions struct {
+	IncludeTranslationNetease  bool   `json:"include_translation_netease"`
+	IncludeRomanizationNetease bool   `json:"include_romanization_netease"`
+	MultiPersonWordByWord      bool   `json:"multi_person_word_by_word"`
+	MusixmatchLanguage         string `json:"musixmatch_language,omitempty"`
+}
+
+var defaultLyricsFetchOptions = LyricsFetchOptions{
+	IncludeTranslationNetease:  false,
+	IncludeRomanizationNetease: false,
+	MultiPersonWordByWord:      true,
+	MusixmatchLanguage:         "",
+}
+
+var (
+	lyricsFetchOptionsMu sync.RWMutex
+	lyricsFetchOptions   = defaultLyricsFetchOptions
+)
+
+func SetLyricsProviderOrder(providers []string) {
+	lyricsProvidersMu.Lock()
+	defer lyricsProvidersMu.Unlock()
+
+	if len(providers) == 0 {
+		lyricsProviders = nil
+		return
+	}
+
+	validNames := map[string]bool{
+		LyricsProviderLRCLIB:     true,
+		LyricsProviderNetease:    true,
+		LyricsProviderMusixmatch: true,
+		LyricsProviderAppleMusic: true,
+		LyricsProviderQQMusic:    true,
+	}
+
+	var valid []string
+	for _, p := range providers {
+		normalized := strings.ToLower(strings.TrimSpace(p))
+		if validNames[normalized] {
+			valid = append(valid, normalized)
+		}
+	}
+
+	lyricsProviders = valid
+	GoLog("[Lyrics] Provider order set to: %v\n", valid)
+}
+
+func GetLyricsProviderOrder() []string {
+	lyricsProvidersMu.RLock()
+	defer lyricsProvidersMu.RUnlock()
+
+	if len(lyricsProviders) == 0 {
+		return DefaultLyricsProviders
+	}
+
+	result := make([]string, len(lyricsProviders))
+	copy(result, lyricsProviders)
+	return result
+}
+
+func GetAvailableLyricsProviders() []map[string]interface{} {
+	return []map[string]interface{}{
+		{"id": LyricsProviderLRCLIB, "name": "LRCLIB", "has_proxy_dependency": false, "description": "Open-source synced lyrics database"},
+		{"id": LyricsProviderNetease, "name": "Netease", "has_proxy_dependency": true, "description": "NetEase Cloud Music lyrics via Paxsenix"},
+		{"id": LyricsProviderMusixmatch, "name": "Musixmatch", "has_proxy_dependency": true, "description": "Musixmatch lyrics via Paxsenix"},
+		{"id": LyricsProviderAppleMusic, "name": "Apple Music", "has_proxy_dependency": true, "description": "Apple Music synced lyrics via Paxsenix"},
+		{"id": LyricsProviderQQMusic, "name": "QQ Music", "has_proxy_dependency": true, "description": "QQ Music lyrics via Paxsenix"},
+	}
+}
+
+func normalizeLyricsFetchOptions(opts LyricsFetchOptions) LyricsFetchOptions {
+	opts.MusixmatchLanguage = strings.ToLower(strings.TrimSpace(opts.MusixmatchLanguage))
+	opts.MusixmatchLanguage = regexp.MustCompile(`[^a-z0-9\-_]`).ReplaceAllString(opts.MusixmatchLanguage, "")
+	if len(opts.MusixmatchLanguage) > 16 {
+		opts.MusixmatchLanguage = opts.MusixmatchLanguage[:16]
+	}
+	return opts
+}
+
+func SetLyricsFetchOptions(opts LyricsFetchOptions) {
+	normalized := normalizeLyricsFetchOptions(opts)
+
+	lyricsFetchOptionsMu.Lock()
+	defer lyricsFetchOptionsMu.Unlock()
+	lyricsFetchOptions = normalized
+
+	GoLog("[Lyrics] Fetch options set: translation=%v romanization=%v multi_person=%v musixmatch_lang=%q\n",
+		normalized.IncludeTranslationNetease,
+		normalized.IncludeRomanizationNetease,
+		normalized.MultiPersonWordByWord,
+		normalized.MusixmatchLanguage,
+	)
+}
+
+func GetLyricsFetchOptions() LyricsFetchOptions {
+	lyricsFetchOptionsMu.RLock()
+	defer lyricsFetchOptionsMu.RUnlock()
+	return lyricsFetchOptions
+}
+
 type lyricsCacheEntry struct {
 	response  *LyricsResponse
 	expiresAt time.Time
@@ -90,6 +212,15 @@ func (c *lyricsCache) Size() int {
 	return len(c.cache)
 }
 
+func (c *lyricsCache) ClearAll() int {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	cleared := len(c.cache)
+	c.cache = make(map[string]*lyricsCacheEntry)
+	return cleared
+}
+
 type LRCLibResponse struct {
 	ID           int     `json:"id"`
 	Name         string  `json:"name"`
@@ -139,7 +270,7 @@ func (c *LyricsClient) FetchLyricsWithMetadata(artist, track string) (*LyricsRes
 	if err != nil {
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
-	req.Header.Set("User-Agent", "SpotiFLAC-Android/1.0")
+	req.Header.Set("User-Agent", getRandomUserAgent())
 
 	resp, err := c.httpClient.Do(req)
 	if err != nil {
@@ -174,7 +305,7 @@ func (c *LyricsClient) FetchLyricsFromLRCLibSearch(query string, durationSec flo
 	if err != nil {
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
-	req.Header.Set("User-Agent", "SpotiFLAC-Android/1.0")
+	req.Header.Set("User-Agent", getRandomUserAgent())
 
 	resp, err := c.httpClient.Do(req)
 	if err != nil {
@@ -233,66 +364,213 @@ func (c *LyricsClient) findBestMatch(results []LRCLibResponse, targetDurationSec
 	return bestPlain
 }
 
+func plainLyricsFromTimedLines(lines []LyricsLine) string {
+	parts := make([]string, 0, len(lines))
+	for _, line := range lines {
+		words := strings.TrimSpace(line.Words)
+		if words == "" {
+			continue
+		}
+		parts = append(parts, words)
+	}
+	return strings.Join(parts, "\n")
+}
+
 func (c *LyricsClient) durationMatches(lrcDuration, targetDuration float64) bool {
 	diff := math.Abs(lrcDuration - targetDuration)
 	return diff <= durationToleranceSec
 }
 
-// durationSec: track duration in seconds for matching, use 0 to skip duration matching
 func (c *LyricsClient) FetchLyricsAllSources(spotifyID, trackName, artistName string, durationSec float64) (*LyricsResponse, error) {
-	// Check cache first
+	primaryArtist := normalizeArtistName(artistName)
+	fetchOptions := GetLyricsFetchOptions()
+
+	extManager := getExtensionManager()
+	var extensionProviders []*extensionProviderWrapper
+	if extManager != nil {
+		extensionProviders = extManager.GetLyricsProviders()
+	}
+
+	var cachedNonExtension *LyricsResponse
 	if cached, found := globalLyricsCache.Get(artistName, trackName, durationSec); found {
-		fmt.Printf("[Lyrics] Cache hit for: %s - %s\n", artistName, trackName)
-		cachedCopy := *cached
-		cachedCopy.Source = cached.Source + " (cached)"
-		return &cachedCopy, nil
+		isExtensionCache := strings.HasPrefix(cached.Source, "Extension:")
+		if len(extensionProviders) == 0 || isExtensionCache {
+			fmt.Printf("[Lyrics] Cache hit for: %s - %s\n", artistName, trackName)
+			cachedCopy := *cached
+			cachedCopy.Source = cached.Source + " (cached)"
+			return &cachedCopy, nil
+		}
+
+		// If extension providers are currently enabled, don't let stale built-in cache
+		// mask newly installed/activated extensions.
+		cachedNonExtension = cached
+		GoLog("[Lyrics] Ignoring cached non-extension lyrics because extension providers are available\n")
 	}
 
-	var lyrics *LyricsResponse
-	var err error
-
-	// Try exact match first
-	lyrics, err = c.FetchLyricsWithMetadata(artistName, trackName)
-	if err == nil && lyrics != nil && len(lyrics.Lines) > 0 {
-		lyrics.Source = "LRCLIB"
-		globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
-		return lyrics, nil
+	isValidResult := func(l *LyricsResponse) bool {
+		return lyricsHasUsableText(l)
 	}
 
-	// Try with simplified track name
-	simplifiedTrack := simplifyTrackName(trackName)
-	if simplifiedTrack != trackName {
-		lyrics, err = c.FetchLyricsWithMetadata(artistName, simplifiedTrack)
-		if err == nil && lyrics != nil && len(lyrics.Lines) > 0 {
-			lyrics.Source = "LRCLIB (simplified)"
-			globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
-			return lyrics, nil
+	if len(extensionProviders) > 0 {
+		for _, provider := range extensionProviders {
+			GoLog("[Lyrics] Trying extension lyrics provider: %s\n", provider.extension.ID)
+			lyrics, err := provider.FetchLyrics(trackName, artistName, "", durationSec)
+			if err == nil && isValidResult(lyrics) {
+				GoLog("[Lyrics] Got lyrics from extension: %s\n", provider.extension.ID)
+				globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
+				return lyrics, nil
+			}
+			if err != nil {
+				GoLog("[Lyrics] Extension %s failed: %v\n", provider.extension.ID, err)
+			}
 		}
 	}
 
-	// Search with duration matching
-	query := artistName + " " + trackName
-	lyrics, err = c.FetchLyricsFromLRCLibSearch(query, durationSec)
-	if err == nil && lyrics != nil && len(lyrics.Lines) > 0 {
-		lyrics.Source = "LRCLIB Search"
-		globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
-		return lyrics, nil
+	if cachedNonExtension != nil {
+		cachedCopy := *cachedNonExtension
+		cachedCopy.Source = cachedNonExtension.Source + " (cached fallback)"
+		GoLog("[Lyrics] Extension providers unavailable for this track, using cached built-in lyrics\n")
+		return &cachedCopy, nil
 	}
 
-	// Search with simplified name and duration matching
-	if simplifiedTrack != trackName {
-		query = artistName + " " + simplifiedTrack
-		lyrics, err = c.FetchLyricsFromLRCLibSearch(query, durationSec)
-		if err == nil && lyrics != nil && len(lyrics.Lines) > 0 {
-			lyrics.Source = "LRCLIB Search (simplified)"
+	providerOrder := GetLyricsProviderOrder()
+	simplifiedTrack := simplifyTrackName(trackName)
+
+	GoLog("[Lyrics] Searching for: %s - %s (providers: %v)\n", artistName, trackName, providerOrder)
+
+	for _, providerName := range providerOrder {
+		GoLog("[Lyrics] Trying provider: %s\n", providerName)
+
+		var lyrics *LyricsResponse
+		var err error
+
+		switch providerName {
+		case LyricsProviderLRCLIB:
+			lyrics, err = c.tryLRCLIB(primaryArtist, artistName, trackName, simplifiedTrack, durationSec)
+
+		case LyricsProviderNetease:
+			neteaseClient := NewNeteaseClient()
+			lyrics, err = neteaseClient.FetchLyrics(
+				trackName,
+				primaryArtist,
+				durationSec,
+				fetchOptions.IncludeTranslationNetease,
+				fetchOptions.IncludeRomanizationNetease,
+			)
+			if err != nil && primaryArtist != artistName {
+				lyrics, err = neteaseClient.FetchLyrics(
+					trackName,
+					artistName,
+					durationSec,
+					fetchOptions.IncludeTranslationNetease,
+					fetchOptions.IncludeRomanizationNetease,
+				)
+			}
+			if err != nil && simplifiedTrack != trackName {
+				lyrics, err = neteaseClient.FetchLyrics(
+					simplifiedTrack,
+					primaryArtist,
+					durationSec,
+					fetchOptions.IncludeTranslationNetease,
+					fetchOptions.IncludeRomanizationNetease,
+				)
+			}
+
+		case LyricsProviderMusixmatch:
+			musixmatchClient := NewMusixmatchClient()
+			lyrics, err = musixmatchClient.FetchLyrics(
+				trackName,
+				primaryArtist,
+				durationSec,
+				fetchOptions.MusixmatchLanguage,
+			)
+			if err != nil && primaryArtist != artistName {
+				lyrics, err = musixmatchClient.FetchLyrics(
+					trackName,
+					artistName,
+					durationSec,
+					fetchOptions.MusixmatchLanguage,
+				)
+			}
+
+		case LyricsProviderAppleMusic:
+			appleClient := NewAppleMusicClient()
+			lyrics, err = appleClient.FetchLyrics(trackName, primaryArtist, durationSec, fetchOptions.MultiPersonWordByWord)
+			if err != nil && primaryArtist != artistName {
+				lyrics, err = appleClient.FetchLyrics(trackName, artistName, durationSec, fetchOptions.MultiPersonWordByWord)
+			}
+
+		case LyricsProviderQQMusic:
+			qqClient := NewQQMusicClient()
+			lyrics, err = qqClient.FetchLyrics(trackName, primaryArtist, durationSec, fetchOptions.MultiPersonWordByWord)
+			if err != nil && primaryArtist != artistName {
+				lyrics, err = qqClient.FetchLyrics(trackName, artistName, durationSec, fetchOptions.MultiPersonWordByWord)
+			}
+
+		default:
+			GoLog("[Lyrics] Unknown provider: %s, skipping\n", providerName)
+			continue
+		}
+
+		if err == nil && isValidResult(lyrics) {
+			GoLog("[Lyrics] Got lyrics from: %s\n", providerName)
 			globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
 			return lyrics, nil
 		}
+
+		if err != nil {
+			GoLog("[Lyrics] Provider %s failed: %v\n", providerName, err)
+		}
 	}
 
 	return nil, fmt.Errorf("lyrics not found from any source")
 }
 
+func (c *LyricsClient) tryLRCLIB(primaryArtist, artistName, trackName, simplifiedTrack string, durationSec float64) (*LyricsResponse, error) {
+	var lyrics *LyricsResponse
+	var err error
+
+	lyrics, err = c.FetchLyricsWithMetadata(primaryArtist, trackName)
+	if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
+		lyrics.Source = "LRCLIB"
+		return lyrics, nil
+	}
+
+	if primaryArtist != artistName {
+		lyrics, err = c.FetchLyricsWithMetadata(artistName, trackName)
+		if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
+			lyrics.Source = "LRCLIB"
+			return lyrics, nil
+		}
+	}
+
+	if simplifiedTrack != trackName {
+		lyrics, err = c.FetchLyricsWithMetadata(primaryArtist, simplifiedTrack)
+		if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
+			lyrics.Source = "LRCLIB (simplified)"
+			return lyrics, nil
+		}
+	}
+
+	query := primaryArtist + " " + trackName
+	lyrics, err = c.FetchLyricsFromLRCLibSearch(query, durationSec)
+	if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
+		lyrics.Source = "LRCLIB Search"
+		return lyrics, nil
+	}
+
+	if simplifiedTrack != trackName {
+		query = primaryArtist + " " + simplifiedTrack
+		lyrics, err = c.FetchLyricsFromLRCLibSearch(query, durationSec)
+		if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
+			lyrics.Source = "LRCLIB Search (simplified)"
+			return lyrics, nil
+		}
+	}
+
+	return nil, fmt.Errorf("LRCLIB: no lyrics found")
+}
+
 func (c *LyricsClient) parseLRCLibResponse(resp *LRCLibResponse) *LyricsResponse {
 	result := &LyricsResponse{
 		Instrumental: resp.Instrumental,
@@ -330,10 +608,20 @@ func parseSyncedLyrics(syncedLyrics string) []LyricsLine {
 			continue
 		}
 
+		// Preserve Apple/QQ background vocal tags by attaching them to
+		// the previous timed line. This keeps [bg:...] in final exported LRC.
+		if strings.HasPrefix(line, "[bg:") && len(lines) > 0 {
+			lines[len(lines)-1].Words = strings.TrimSpace(lines[len(lines)-1].Words + "\n" + line)
+			continue
+		}
+
 		matches := lrcPattern.FindStringSubmatch(line)
 		if len(matches) == 5 {
 			startMs := lrcTimestampToMs(matches[1], matches[2], matches[3])
 			words := strings.TrimSpace(matches[4])
+			if words == "" {
+				continue
+			}
 
 			lines = append(lines, LyricsLine{
 				StartTimeMs: startMs,
@@ -354,6 +642,77 @@ func parseSyncedLyrics(syncedLyrics string) []LyricsLine {
 	return lines
 }
 
+func plainTextLyricsLines(rawLyrics string) []LyricsLine {
+	var lines []LyricsLine
+	for _, line := range strings.Split(rawLyrics, "\n") {
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" {
+			continue
+		}
+		lines = append(lines, LyricsLine{
+			StartTimeMs: 0,
+			Words:       trimmed,
+			EndTimeMs:   0,
+		})
+	}
+	return lines
+}
+
+func lyricsHasUsableText(lyrics *LyricsResponse) bool {
+	if lyrics == nil {
+		return false
+	}
+	if lyrics.Instrumental {
+		return true
+	}
+	if strings.TrimSpace(lyrics.PlainLyrics) != "" {
+		return true
+	}
+	for _, line := range lyrics.Lines {
+		if strings.TrimSpace(line.Words) != "" {
+			return true
+		}
+	}
+	return false
+}
+
+func detectLyricsErrorPayload(raw string) (string, bool) {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" || !strings.HasPrefix(trimmed, "{") {
+		return "", false
+	}
+
+	var payload map[string]interface{}
+	if err := json.Unmarshal([]byte(trimmed), &payload); err != nil {
+		return "", false
+	}
+
+	lyricsKeys := []string{"lyrics", "lyric", "lrc", "content", "lines", "syncedLyrics", "unsyncedLyrics"}
+	hasLyricsKey := false
+	for _, key := range lyricsKeys {
+		if _, ok := payload[key]; ok {
+			hasLyricsKey = true
+			break
+		}
+	}
+
+	errorKeys := []string{"message", "error", "detail", "reason"}
+	for _, key := range errorKeys {
+		if msg, ok := payload[key].(string); ok {
+			msg = strings.TrimSpace(msg)
+			if msg != "" && !hasLyricsKey {
+				return msg, true
+			}
+		}
+	}
+
+	if success, ok := payload["success"].(bool); ok && !success && !hasLyricsKey {
+		return "request unsuccessful", true
+	}
+
+	return "", false
+}
+
 func lrcTimestampToMs(minutes, seconds, centiseconds string) int64 {
 	min, _ := strconv.ParseInt(minutes, 10, 64)
 	sec, _ := strconv.ParseInt(seconds, 10, 64)
@@ -367,40 +726,18 @@ func lrcTimestampToMs(minutes, seconds, centiseconds string) int64 {
 }
 
 func msToLRCTimestamp(ms int64) string {
+	return fmt.Sprintf("[%s]", msToLRCTimestampInline(ms))
+}
+
+func msToLRCTimestampInline(ms int64) string {
 	totalSeconds := ms / 1000
 	minutes := totalSeconds / 60
 	seconds := totalSeconds % 60
 	centiseconds := (ms % 1000) / 10
 
-	return fmt.Sprintf("[%02d:%02d.%02d]", minutes, seconds, centiseconds)
+	return fmt.Sprintf("%02d:%02d.%02d", minutes, seconds, centiseconds)
 }
 
-// Use convertToLRCWithMetadata for full LRC with headers
-// Kept for potential future use
-// func convertToLRC(lyrics *LyricsResponse) string {
-// 	if lyrics == nil || len(lyrics.Lines) == 0 {
-// 		return ""
-// 	}
-//
-// 	var builder strings.Builder
-//
-// 	if lyrics.SyncType == "LINE_SYNCED" {
-// 		for _, line := range lyrics.Lines {
-// 			timestamp := msToLRCTimestamp(line.StartTimeMs)
-// 			builder.WriteString(timestamp)
-// 			builder.WriteString(line.Words)
-// 			builder.WriteString("\n")
-// 		}
-// 	} else {
-// 		for _, line := range lyrics.Lines {
-// 			builder.WriteString(line.Words)
-// 			builder.WriteString("\n")
-// 		}
-// 	}
-//
-// 	return builder.String()
-// }
-
 func convertToLRCWithMetadata(lyrics *LyricsResponse, trackName, artistName string) string {
 	if lyrics == nil || len(lyrics.Lines) == 0 {
 		return ""
@@ -410,7 +747,7 @@ func convertToLRCWithMetadata(lyrics *LyricsResponse, trackName, artistName stri
 
 	builder.WriteString(fmt.Sprintf("[ti:%s]\n", trackName))
 	builder.WriteString(fmt.Sprintf("[ar:%s]\n", artistName))
-	builder.WriteString("[by:SpotiFLAC-Mobile]\n")
+	builder.WriteString("[by:Implemented by SpotiFLAC-Mobile using Paxsenix API]\n")
 	builder.WriteString("\n")
 
 	if lyrics.SyncType == "LINE_SYNCED" {
@@ -458,6 +795,28 @@ func simplifyTrackName(name string) string {
 		re := regexp.MustCompile("(?i)" + pattern)
 		result = re.ReplaceAllString(result, "")
 	}
+	result = strings.TrimSpace(result)
+	if result == "" {
+		return result
+	}
+
+	if loose := normalizeLooseTitle(result); loose != "" {
+		return loose
+	}
+
+	return result
+}
+
+func normalizeArtistName(name string) string {
+	separators := []string{", ", "; ", " & ", " feat. ", " ft. ", " featuring ", " with "}
+
+	result := name
+	for _, sep := range separators {
+		if idx := strings.Index(strings.ToLower(result), strings.ToLower(sep)); idx > 0 {
+			result = result[:idx]
+			break
+		}
+	}
 
 	return strings.TrimSpace(result)
 }

go_backend/lyrics_apple.go

@@ -0,0 +1,296 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"math"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+type AppleMusicClient struct {
+	httpClient *http.Client
+}
+
+type appleMusicSearchResult struct {
+	ID         string `json:"id"`
+	SongName   string `json:"songName"`
+	ArtistName string `json:"artistName"`
+	AlbumName  string `json:"albumName"`
+	Duration   int    `json:"duration"`
+}
+
+type paxResponse struct {
+	Type    string      `json:"type"`    // "Syllable" or "Line"
+	Content []paxLyrics `json:"content"` // List of lyric lines
+}
+
+type paxLyrics struct {
+	Text           []paxLyricDetail `json:"text"`
+	Timestamp      int              `json:"timestamp"`
+	OppositeTurn   bool             `json:"oppositeTurn"`
+	Background     bool             `json:"background"`
+	BackgroundText []paxLyricDetail `json:"backgroundText"`
+	EndTime        int              `json:"endtime"`
+}
+
+type paxLyricDetail struct {
+	Text      string `json:"text"`
+	Part      bool   `json:"part"`
+	Timestamp *int   `json:"timestamp"`
+	EndTime   *int   `json:"endtime"`
+}
+
+func NewAppleMusicClient() *AppleMusicClient {
+	return &AppleMusicClient{
+		httpClient: NewMetadataHTTPClient(20 * time.Second),
+	}
+}
+
+func selectBestAppleMusicSearchResult(results []appleMusicSearchResult, trackName, artistName string, durationSec float64) *appleMusicSearchResult {
+	if len(results) == 0 {
+		return nil
+	}
+
+	normalizedTrack := strings.ToLower(strings.TrimSpace(simplifyTrackName(trackName)))
+	normalizedArtist := strings.ToLower(strings.TrimSpace(normalizeArtistName(artistName)))
+	if normalizedArtist == "" {
+		normalizedArtist = strings.ToLower(strings.TrimSpace(artistName))
+	}
+
+	bestIndex := 0
+	bestScore := -1
+	for i := range results {
+		result := &results[i]
+		score := 0
+
+		candidateTrack := strings.ToLower(strings.TrimSpace(simplifyTrackName(result.SongName)))
+		candidateArtist := strings.ToLower(strings.TrimSpace(normalizeArtistName(result.ArtistName)))
+
+		switch {
+		case candidateTrack == normalizedTrack:
+			score += 50
+		case strings.Contains(candidateTrack, normalizedTrack) || strings.Contains(normalizedTrack, candidateTrack):
+			score += 25
+		}
+
+		switch {
+		case candidateArtist == normalizedArtist:
+			score += 60
+		case strings.Contains(candidateArtist, normalizedArtist) || strings.Contains(normalizedArtist, candidateArtist):
+			score += 30
+		}
+
+		if durationSec > 0 && result.Duration > 0 {
+			diff := math.Abs(float64(result.Duration)/1000.0 - durationSec)
+			if diff <= durationToleranceSec {
+				score += 20
+			}
+		}
+
+		if score > bestScore {
+			bestScore = score
+			bestIndex = i
+		}
+	}
+
+	return &results[bestIndex]
+}
+
+func (c *AppleMusicClient) SearchSong(trackName, artistName string, durationSec float64) (string, error) {
+	query := trackName + " " + artistName
+	if strings.TrimSpace(query) == "" {
+		return "", fmt.Errorf("empty search query")
+	}
+
+	encodedQuery := url.QueryEscape(query)
+	searchURL := fmt.Sprintf("https://lyrics.paxsenix.org/apple-music/search?q=%s", encodedQuery)
+
+	req, err := http.NewRequest("GET", searchURL, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("User-Agent", getRandomUserAgent())
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("apple music search failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return "", fmt.Errorf("apple music search returned HTTP %d", resp.StatusCode)
+	}
+
+	var searchResp []appleMusicSearchResult
+	if err := json.NewDecoder(resp.Body).Decode(&searchResp); err != nil {
+		return "", fmt.Errorf("failed to decode apple music response: %w", err)
+	}
+
+	best := selectBestAppleMusicSearchResult(searchResp, trackName, artistName, durationSec)
+	if best == nil || strings.TrimSpace(best.ID) == "" {
+		return "", fmt.Errorf("no songs found on apple music")
+	}
+
+	return strings.TrimSpace(best.ID), nil
+}
+
+func (c *AppleMusicClient) FetchLyricsByID(songID string) (string, error) {
+	lyricsURL := fmt.Sprintf("https://lyrics.paxsenix.org/apple-music/lyrics?id=%s", songID)
+
+	req, err := http.NewRequest("GET", lyricsURL, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("apple music lyrics fetch failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return "", fmt.Errorf("apple music lyrics proxy returned HTTP %d", resp.StatusCode)
+	}
+
+	bodyBytes, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read lyrics response: %w", err)
+	}
+
+	bodyStr := strings.TrimSpace(string(bodyBytes))
+	if bodyStr == "" {
+		return "", fmt.Errorf("empty lyrics response from apple music")
+	}
+
+	return bodyStr, nil
+}
+
+func formatPaxLyricsToLRC(rawJSON string, multiPersonWordByWord bool) (string, error) {
+	var paxResp paxResponse
+	if err := json.Unmarshal([]byte(rawJSON), &paxResp); err == nil && paxResp.Content != nil {
+		return formatPaxContent(paxResp.Type, paxResp.Content, multiPersonWordByWord), nil
+	}
+
+	var directLyrics []paxLyrics
+	if err := json.Unmarshal([]byte(rawJSON), &directLyrics); err == nil && len(directLyrics) > 0 {
+		return formatPaxContent("Syllable", directLyrics, multiPersonWordByWord), nil
+	}
+
+	return "", fmt.Errorf("failed to parse pax lyrics response")
+}
+
+func appendPaxLyricDetail(builder *strings.Builder, details []paxLyricDetail) {
+	lastStart := ""
+
+	for _, syllable := range details {
+		if syllable.Timestamp != nil {
+			start := fmt.Sprintf("<%s>", msToLRCTimestampInline(int64(*syllable.Timestamp)))
+			if start != lastStart {
+				builder.WriteString(start)
+				lastStart = start
+			}
+		}
+
+		builder.WriteString(syllable.Text)
+		if !syllable.Part {
+			builder.WriteString(" ")
+		}
+
+		if syllable.EndTime != nil {
+			builder.WriteString(fmt.Sprintf("<%s>", msToLRCTimestampInline(int64(*syllable.EndTime))))
+		}
+	}
+}
+
+func formatPaxContent(lyricsType string, content []paxLyrics, multiPersonWordByWord bool) string {
+	var sb strings.Builder
+
+	for i, line := range content {
+		if i > 0 {
+			sb.WriteString("\n")
+		}
+
+		timestamp := msToLRCTimestamp(int64(line.Timestamp))
+
+		if strings.EqualFold(lyricsType, "Syllable") {
+			sb.WriteString(timestamp)
+			if multiPersonWordByWord {
+				if line.OppositeTurn {
+					sb.WriteString("v2:")
+				} else {
+					sb.WriteString("v1:")
+				}
+			}
+
+			appendPaxLyricDetail(&sb, line.Text)
+
+			if line.Background && multiPersonWordByWord && len(line.BackgroundText) > 0 {
+				sb.WriteString("\n[bg:")
+				appendPaxLyricDetail(&sb, line.BackgroundText)
+				sb.WriteString("]")
+			}
+		} else {
+			if len(line.Text) > 0 {
+				sb.WriteString(timestamp)
+				sb.WriteString(line.Text[0].Text)
+			}
+		}
+	}
+
+	return strings.TrimSpace(sb.String())
+}
+
+func (c *AppleMusicClient) FetchLyrics(
+	trackName,
+	artistName string,
+	durationSec float64,
+	multiPersonWordByWord bool,
+) (*LyricsResponse, error) {
+	songID, err := c.SearchSong(trackName, artistName, durationSec)
+	if err != nil {
+		return nil, err
+	}
+
+	rawLyrics, err := c.FetchLyricsByID(songID)
+	if err != nil {
+		return nil, err
+	}
+	if errMsg, isErrorPayload := detectLyricsErrorPayload(rawLyrics); isErrorPayload {
+		return nil, fmt.Errorf("apple music proxy returned non-lyric payload: %s", errMsg)
+	}
+
+	lrcText, err := formatPaxLyricsToLRC(rawLyrics, multiPersonWordByWord)
+	if err != nil {
+		lrcText = rawLyrics
+	}
+
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) > 0 {
+		return &LyricsResponse{
+			Lines:    lines,
+			SyncType: "LINE_SYNCED",
+			Provider: "Apple Music",
+			Source:   "Apple Music",
+		}, nil
+	}
+
+	resultLines := plainTextLyricsLines(lrcText)
+
+	if len(resultLines) > 0 {
+		return &LyricsResponse{
+			Lines:    resultLines,
+			SyncType: "UNSYNCED",
+			Provider: "Apple Music",
+			Source:   "Apple Music",
+		}, nil
+	}
+
+	return nil, fmt.Errorf("no lyrics found on apple music")
+}

go_backend/lyrics_musixmatch.go

@@ -0,0 +1,188 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"math"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+type MusixmatchClient struct {
+	httpClient *http.Client
+	baseURL    string
+}
+
+type musixmatchSearchResponse struct {
+	ID                 int64                     `json:"id"`
+	SongName           string                    `json:"songName"`
+	ArtistName         string                    `json:"artistName"`
+	AlbumName          string                    `json:"albumName"`
+	Artwork            string                    `json:"artwork"`
+	ReleaseDate        string                    `json:"releaseDate"`
+	Duration           int                       `json:"duration"`
+	URL                string                    `json:"url"`
+	AlbumID            int64                     `json:"albumId"`
+	HasSyncedLyrics    bool                      `json:"hasSyncedLyrics"`
+	HasUnsyncedLyrics  bool                      `json:"hasUnsyncedLyrics"`
+	AvailableLanguages []string                  `json:"availableLanguages"`
+	OriginalLanguage   string                    `json:"originalLanguage"`
+	SyncedLyrics       *musixmatchLyricsResponse `json:"syncedLyrics"`
+	UnsyncedLyrics     *musixmatchLyricsResponse `json:"unsyncedLyrics"`
+}
+
+type musixmatchLyricsResponse struct {
+	ID          int64  `json:"id"`
+	Duration    int    `json:"duration"`
+	Language    string `json:"language"`
+	UpdatedTime string `json:"updatedTime"`
+	Lyrics      string `json:"lyrics"`
+}
+
+func NewMusixmatchClient() *MusixmatchClient {
+	return &MusixmatchClient{
+		httpClient: NewMetadataHTTPClient(15 * time.Second),
+		baseURL:    "https://lyrics.paxsenix.org/musixmatch/lyrics",
+	}
+}
+
+func (c *MusixmatchClient) fetchLyricsPayload(trackName, artistName string, durationSec float64, lyricsType, language string) (string, error) {
+	if strings.TrimSpace(trackName) == "" || strings.TrimSpace(artistName) == "" {
+		return "", fmt.Errorf("empty track or artist name")
+	}
+
+	params := url.Values{}
+	params.Set("t", trackName)
+	params.Set("a", artistName)
+	params.Set("type", lyricsType)
+	params.Set("format", "lrc")
+	if durationSec > 0 {
+		params.Set("d", fmt.Sprintf("%d", int(math.Round(durationSec))))
+	}
+	if strings.TrimSpace(language) != "" {
+		params.Set("l", strings.ToLower(strings.TrimSpace(language)))
+	}
+	fullURL := c.baseURL + "?" + params.Encode()
+
+	req, err := http.NewRequest("GET", fullURL, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("musixmatch request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read musixmatch response: %w", err)
+	}
+
+	if resp.StatusCode != 200 {
+		trimmed := strings.TrimSpace(string(body))
+		if errMsg, isErrorPayload := detectLyricsErrorPayload(trimmed); isErrorPayload {
+			return "", fmt.Errorf("musixmatch proxy returned HTTP %d: %s", resp.StatusCode, errMsg)
+		}
+		return "", fmt.Errorf("musixmatch proxy returned HTTP %d", resp.StatusCode)
+	}
+
+	var lrcPayload string
+	if err := json.Unmarshal(body, &lrcPayload); err == nil {
+		lrcPayload = strings.TrimSpace(lrcPayload)
+		if lrcPayload == "" {
+			return "", fmt.Errorf("empty musixmatch lyrics payload")
+		}
+		return lrcPayload, nil
+	}
+
+	trimmed := strings.TrimSpace(string(body))
+	if errMsg, isErrorPayload := detectLyricsErrorPayload(trimmed); isErrorPayload {
+		return "", fmt.Errorf("%s", errMsg)
+	}
+	if trimmed != "" && !strings.HasPrefix(trimmed, "{") {
+		return trimmed, nil
+	}
+	return "", fmt.Errorf("failed to decode musixmatch response")
+}
+
+func (c *MusixmatchClient) FetchLyricsInLanguage(trackName, artistName string, durationSec float64, language string) (*LyricsResponse, error) {
+	lang := strings.ToLower(strings.TrimSpace(language))
+	if lang == "" {
+		return nil, fmt.Errorf("invalid language")
+	}
+
+	lrcText, err := c.fetchLyricsPayload(trackName, artistName, durationSec, "translate", lang)
+	if err != nil {
+		return nil, err
+	}
+
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) > 0 {
+		return &LyricsResponse{
+			Lines:       lines,
+			SyncType:    "LINE_SYNCED",
+			PlainLyrics: plainLyricsFromTimedLines(lines),
+			Provider:    "Musixmatch",
+			Source:      fmt.Sprintf("Musixmatch (%s)", lang),
+		}, nil
+	}
+
+	plainLines := plainTextLyricsLines(lrcText)
+	if len(plainLines) > 0 {
+		return &LyricsResponse{
+			Lines:       plainLines,
+			SyncType:    "UNSYNCED",
+			PlainLyrics: lrcText,
+			Provider:    "Musixmatch",
+			Source:      fmt.Sprintf("Musixmatch (%s)", lang),
+		}, nil
+	}
+
+	return nil, fmt.Errorf("no lyrics found on musixmatch for language %s", lang)
+}
+
+func (c *MusixmatchClient) FetchLyrics(trackName, artistName string, durationSec float64, preferredLanguage string) (*LyricsResponse, error) {
+	if preferred := strings.ToLower(strings.TrimSpace(preferredLanguage)); preferred != "" {
+		localized, localizedErr := c.FetchLyricsInLanguage(trackName, artistName, durationSec, preferred)
+		if localizedErr == nil {
+			return localized, nil
+		}
+		GoLog("[Musixmatch] Language override '%s' failed: %v\n", preferred, localizedErr)
+	}
+
+	lrcText, err := c.fetchLyricsPayload(trackName, artistName, durationSec, "word", "")
+	if err != nil {
+		return nil, err
+	}
+
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) > 0 {
+		return &LyricsResponse{
+			Lines:       lines,
+			SyncType:    "LINE_SYNCED",
+			PlainLyrics: plainLyricsFromTimedLines(lines),
+			Provider:    "Musixmatch",
+			Source:      "Musixmatch",
+		}, nil
+	}
+
+	plainLines := plainTextLyricsLines(lrcText)
+	if len(plainLines) > 0 {
+		return &LyricsResponse{
+			Lines:       plainLines,
+			SyncType:    "UNSYNCED",
+			PlainLyrics: lrcText,
+			Provider:    "Musixmatch",
+			Source:      "Musixmatch",
+		}, nil
+	}
+
+	return nil, fmt.Errorf("no lyrics found on musixmatch")
+}

go_backend/lyrics_netease.go

@@ -0,0 +1,195 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+type NeteaseClient struct {
+	httpClient *http.Client
+}
+
+type neteaseSearchResponse struct {
+	Result struct {
+		Songs []struct {
+			Name    string `json:"name"`
+			ID      int64  `json:"id"`
+			Artists []struct {
+				Name string `json:"name"`
+			} `json:"artists"`
+		} `json:"songs"`
+		SongCount int `json:"songCount"`
+	} `json:"result"`
+	Code int `json:"code"`
+}
+
+type neteaseLyricsResponse struct {
+	LRC     *neteaseLyricField `json:"lrc"`
+	TLyric  *neteaseLyricField `json:"tlyric"`
+	RomaLRC *neteaseLyricField `json:"romalrc"`
+	Code    int                `json:"code"`
+}
+
+type neteaseLyricField struct {
+	Lyric string `json:"lyric"`
+}
+
+var neteaseHeaders = map[string]string{
+	"Accept":          "application/json",
+	"Accept-Language": "en-US,en;q=0.9",
+	"Cache-Control":   "max-age=0",
+}
+
+func NewNeteaseClient() *NeteaseClient {
+	return &NeteaseClient{
+		httpClient: NewMetadataHTTPClient(15 * time.Second),
+	}
+}
+
+func (c *NeteaseClient) SearchSong(trackName, artistName string) (int64, error) {
+	query := trackName + " " + artistName
+	if strings.TrimSpace(query) == "" {
+		return 0, fmt.Errorf("empty search query")
+	}
+
+	searchURL := "https://lyrics.paxsenix.org/netease/search"
+	params := url.Values{}
+	params.Set("q", query)
+
+	fullURL := searchURL + "?" + params.Encode()
+
+	req, err := http.NewRequest("GET", fullURL, nil)
+	if err != nil {
+		return 0, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	for k, v := range neteaseHeaders {
+		req.Header.Set(k, v)
+	}
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return 0, fmt.Errorf("netease search failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return 0, fmt.Errorf("netease search returned HTTP %d", resp.StatusCode)
+	}
+
+	var searchResp neteaseSearchResponse
+	if err := json.NewDecoder(resp.Body).Decode(&searchResp); err != nil {
+		return 0, fmt.Errorf("failed to decode netease search: %w", err)
+	}
+
+	if searchResp.Result.SongCount == 0 || len(searchResp.Result.Songs) == 0 {
+		return 0, fmt.Errorf("no songs found on netease")
+	}
+
+	return searchResp.Result.Songs[0].ID, nil
+}
+
+func (c *NeteaseClient) FetchLyricsByID(songID int64, includeTranslation, includeRomanization bool) (string, error) {
+	lyricsURL := "https://lyrics.paxsenix.org/netease/lyrics"
+	params := url.Values{}
+	params.Set("id", fmt.Sprintf("%d", songID))
+
+	fullURL := lyricsURL + "?" + params.Encode()
+
+	req, err := http.NewRequest("GET", fullURL, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+
+	for k, v := range neteaseHeaders {
+		req.Header.Set(k, v)
+	}
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("netease lyrics fetch failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return "", fmt.Errorf("netease lyrics returned HTTP %d", resp.StatusCode)
+	}
+
+	var lyricsResp neteaseLyricsResponse
+	if err := json.NewDecoder(resp.Body).Decode(&lyricsResp); err != nil {
+		return "", fmt.Errorf("failed to decode netease lyrics: %w", err)
+	}
+
+	if lyricsResp.LRC == nil || strings.TrimSpace(lyricsResp.LRC.Lyric) == "" {
+		return "", fmt.Errorf("no lyrics available on netease")
+	}
+
+	lyric := lyricsResp.LRC.Lyric
+
+	if includeTranslation && lyricsResp.TLyric != nil && strings.TrimSpace(lyricsResp.TLyric.Lyric) != "" {
+		lyric += "\n\n" + lyricsResp.TLyric.Lyric
+	}
+
+	if includeRomanization && lyricsResp.RomaLRC != nil && strings.TrimSpace(lyricsResp.RomaLRC.Lyric) != "" {
+		lyric += "\n\n" + lyricsResp.RomaLRC.Lyric
+	}
+
+	return lyric, nil
+}
+
+func (c *NeteaseClient) FetchLyrics(
+	trackName,
+	artistName string,
+	durationSec float64,
+	includeTranslation,
+	includeRomanization bool,
+) (*LyricsResponse, error) {
+	songID, err := c.SearchSong(trackName, artistName)
+	if err != nil {
+		return nil, err
+	}
+
+	lrcText, err := c.FetchLyricsByID(songID, includeTranslation, includeRomanization)
+	if err != nil {
+		return nil, err
+	}
+
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) == 0 {
+		plainLines := strings.Split(lrcText, "\n")
+		for _, line := range plainLines {
+			trimmed := strings.TrimSpace(line)
+			if trimmed != "" {
+				lines = append(lines, LyricsLine{
+					StartTimeMs: 0,
+					Words:       trimmed,
+					EndTimeMs:   0,
+				})
+			}
+		}
+
+		if len(lines) == 0 {
+			return nil, fmt.Errorf("netease returned empty lyrics")
+		}
+
+		return &LyricsResponse{
+			Lines:    lines,
+			SyncType: "UNSYNCED",
+			Provider: "Netease",
+			Source:   "Netease",
+		}, nil
+	}
+
+	return &LyricsResponse{
+		Lines:    lines,
+		SyncType: "LINE_SYNCED",
+		Provider: "Netease",
+		Source:   "Netease",
+	}, nil
+}

go_backend/lyrics_qqmusic.go

@@ -0,0 +1,138 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"math"
+	"net/http"
+	"strings"
+	"time"
+)
+
+type QQMusicClient struct {
+	httpClient *http.Client
+}
+
+type qqLyricsMetadataRequest struct {
+	Artist   []string `json:"artist"`
+	Album    string   `json:"album,omitempty"`
+	SongID   int64    `json:"songid,omitempty"`
+	Title    string   `json:"title"`
+	Duration int64    `json:"duration,omitempty"`
+}
+
+type qqLyricsMetadataResponse struct {
+	Lyrics []paxLyrics `json:"lyrics"`
+}
+
+func NewQQMusicClient() *QQMusicClient {
+	return &QQMusicClient{
+		httpClient: NewMetadataHTTPClient(15 * time.Second),
+	}
+}
+
+func (c *QQMusicClient) fetchLyricsByMetadata(trackName, artistName string, durationSec float64) (string, error) {
+	payload := qqLyricsMetadataRequest{
+		Artist: []string{artistName},
+		Title:  trackName,
+	}
+	if durationSec > 0 {
+		payload.Duration = int64(math.Round(durationSec))
+	}
+
+	lyricsURL := "https://lyrics.paxsenix.org/qq/lyrics-metadata"
+
+	payloadBytes, err := json.Marshal(payload)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal payload: %w", err)
+	}
+
+	req, err := http.NewRequest("POST", lyricsURL, strings.NewReader(string(payloadBytes)))
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("qqmusic lyrics fetch failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return "", fmt.Errorf("qqmusic lyrics proxy returned HTTP %d", resp.StatusCode)
+	}
+
+	bodyBytes, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read lyrics response: %w", err)
+	}
+
+	bodyStr := strings.TrimSpace(string(bodyBytes))
+	if bodyStr == "" {
+		return "", fmt.Errorf("empty lyrics response from qqmusic")
+	}
+
+	return bodyStr, nil
+}
+
+func formatQQLyricsMetadataToLRC(rawJSON string, multiPersonWordByWord bool) (string, error) {
+	var response qqLyricsMetadataResponse
+	if err := json.Unmarshal([]byte(rawJSON), &response); err != nil {
+		return "", fmt.Errorf("failed to parse qq metadata lyrics response")
+	}
+	if len(response.Lyrics) == 0 {
+		return "", fmt.Errorf("qq metadata lyrics response was empty")
+	}
+	return formatPaxContent("Syllable", response.Lyrics, multiPersonWordByWord), nil
+}
+
+func (c *QQMusicClient) FetchLyrics(
+	trackName,
+	artistName string,
+	durationSec float64,
+	multiPersonWordByWord bool,
+) (*LyricsResponse, error) {
+	rawLyrics, err := c.fetchLyricsByMetadata(trackName, artistName, durationSec)
+	if err != nil {
+		return nil, err
+	}
+	if errMsg, isErrorPayload := detectLyricsErrorPayload(rawLyrics); isErrorPayload {
+		return nil, fmt.Errorf("qqmusic proxy returned non-lyric payload: %s", errMsg)
+	}
+
+	lrcText, err := formatQQLyricsMetadataToLRC(rawLyrics, multiPersonWordByWord)
+	if err != nil {
+		if fallback, fallbackErr := formatPaxLyricsToLRC(rawLyrics, multiPersonWordByWord); fallbackErr == nil {
+			lrcText = fallback
+		} else {
+			lrcText = rawLyrics
+		}
+	}
+
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) > 0 {
+		return &LyricsResponse{
+			Lines:    lines,
+			SyncType: "LINE_SYNCED",
+			Provider: "QQ Music",
+			Source:   "QQ Music",
+		}, nil
+	}
+
+	resultLines := plainTextLyricsLines(lrcText)
+
+	if len(resultLines) > 0 {
+		return &LyricsResponse{
+			Lines:    resultLines,
+			SyncType: "UNSYNCED",
+			Provider: "QQ Music",
+			Source:   "QQ Music",
+		}, nil
+	}
+
+	return nil, fmt.Errorf("no lyrics found on qqmusic")
+}

go_backend/metadata_artist_tags_test.go

@@ -0,0 +1,67 @@
+package gobackend
+
+import (
+	"bytes"
+	"encoding/binary"
+	"slices"
+	"testing"
+
+	"github.com/go-flac/flacvorbis/v2"
+)
+
+func TestSplitArtistTagValues(t *testing.T) {
+	got := splitArtistTagValues("Artist A, Artist B feat. Artist C & Artist B")
+	want := []string{"Artist A", "Artist B", "Artist C"}
+	if !slices.Equal(got, want) {
+		t.Fatalf("splitArtistTagValues() = %#v, want %#v", got, want)
+	}
+}
+
+func TestSetArtistCommentsSplitVorbis(t *testing.T) {
+	cmt := flacvorbis.New()
+	setArtistComments(cmt, "ARTIST", "Artist A, Artist B", artistTagModeSplitVorbis)
+
+	got := getCommentValues(cmt, "ARTIST")
+	want := []string{"Artist A", "Artist B"}
+	if !slices.Equal(got, want) {
+		t.Fatalf("getCommentValues(ARTIST) = %#v, want %#v", got, want)
+	}
+}
+
+func TestParseVorbisCommentsJoinsRepeatedArtists(t *testing.T) {
+	metadata := &AudioMetadata{}
+	parseVorbisComments(
+		buildVorbisCommentPayload(
+			[]string{
+				"TITLE=Song",
+				"ARTIST=Artist A",
+				"ARTIST=Artist B",
+				"ALBUMARTIST=Album Artist A",
+				"ALBUMARTIST=Album Artist B",
+			},
+		),
+		metadata,
+	)
+
+	if metadata.Title != "Song" {
+		t.Fatalf("title = %q", metadata.Title)
+	}
+	if metadata.Artist != "Artist A, Artist B" {
+		t.Fatalf("artist = %q", metadata.Artist)
+	}
+	if metadata.AlbumArtist != "Album Artist A, Album Artist B" {
+		t.Fatalf("album artist = %q", metadata.AlbumArtist)
+	}
+}
+
+func buildVorbisCommentPayload(comments []string) []byte {
+	var buf bytes.Buffer
+	_ = binary.Write(&buf, binary.LittleEndian, uint32(len("spotiflac")))
+	buf.WriteString("spotiflac")
+	_ = binary.Write(&buf, binary.LittleEndian, uint32(len(comments)))
+	for _, comment := range comments {
+		_ = binary.Write(&buf, binary.LittleEndian, uint32(len(comment)))
+		buf.WriteString(comment)
+	}
+	return buf.Bytes()
+}

go_backend/metadata_types.go

@@ -0,0 +1,149 @@
+package gobackend
+
+import "time"
+
+type cacheEntry struct {
+	data      interface{}
+	expiresAt time.Time
+}
+
+func (e *cacheEntry) isExpired() bool {
+	return time.Now().After(e.expiresAt)
+}
+
+type TrackMetadata struct {
+	SpotifyID   string `json:"spotify_id,omitempty"`
+	Artists     string `json:"artists"`
+	Name        string `json:"name"`
+	AlbumName   string `json:"album_name"`
+	AlbumArtist string `json:"album_artist,omitempty"`
+	DurationMS  int    `json:"duration_ms"`
+	Images      string `json:"images"`
+	ReleaseDate string `json:"release_date"`
+	TrackNumber int    `json:"track_number"`
+	TotalTracks int    `json:"total_tracks,omitempty"`
+	DiscNumber  int    `json:"disc_number,omitempty"`
+	TotalDiscs  int    `json:"total_discs,omitempty"`
+	ExternalURL string `json:"external_urls"`
+	ISRC        string `json:"isrc"`
+	AlbumID     string `json:"album_id,omitempty"`
+	ArtistID    string `json:"artist_id,omitempty"`
+	AlbumType   string `json:"album_type,omitempty"`
+	Composer    string `json:"composer,omitempty"`
+}
+
+type AlbumTrackMetadata struct {
+	SpotifyID   string `json:"spotify_id,omitempty"`
+	Artists     string `json:"artists"`
+	Name        string `json:"name"`
+	AlbumName   string `json:"album_name"`
+	AlbumArtist string `json:"album_artist,omitempty"`
+	DurationMS  int    `json:"duration_ms"`
+	Images      string `json:"images"`
+	ReleaseDate string `json:"release_date"`
+	TrackNumber int    `json:"track_number"`
+	TotalTracks int    `json:"total_tracks,omitempty"`
+	DiscNumber  int    `json:"disc_number,omitempty"`
+	TotalDiscs  int    `json:"total_discs,omitempty"`
+	ExternalURL string `json:"external_urls"`
+	ISRC        string `json:"isrc"`
+	AlbumID     string `json:"album_id,omitempty"`
+	AlbumURL    string `json:"album_url,omitempty"`
+	AlbumType   string `json:"album_type,omitempty"`
+	Composer    string `json:"composer,omitempty"`
+}
+
+type AlbumInfoMetadata struct {
+	TotalTracks int    `json:"total_tracks"`
+	Name        string `json:"name"`
+	ReleaseDate string `json:"release_date"`
+	Artists     string `json:"artists"`
+	ArtistId    string `json:"artist_id,omitempty"`
+	Images      string `json:"images"`
+	Genre       string `json:"genre,omitempty"`
+	Label       string `json:"label,omitempty"`
+	Copyright   string `json:"copyright,omitempty"`
+}
+
+type AlbumResponsePayload struct {
+	AlbumInfo AlbumInfoMetadata    `json:"album_info"`
+	TrackList []AlbumTrackMetadata `json:"track_list"`
+}
+
+type PlaylistInfoMetadata struct {
+	Name   string `json:"name,omitempty"`
+	Images string `json:"images,omitempty"`
+	Tracks struct {
+		Total int `json:"total"`
+	} `json:"tracks"`
+	Owner struct {
+		DisplayName string `json:"display_name"`
+		Name        string `json:"name"`
+		Images      string `json:"images"`
+	} `json:"owner"`
+}
+
+type PlaylistResponsePayload struct {
+	PlaylistInfo PlaylistInfoMetadata `json:"playlist_info"`
+	TrackList    []AlbumTrackMetadata `json:"track_list"`
+}
+
+type ArtistInfoMetadata struct {
+	ID         string `json:"id"`
+	Name       string `json:"name"`
+	Images     string `json:"images"`
+	Followers  int    `json:"followers"`
+	Popularity int    `json:"popularity"`
+}
+
+type ArtistAlbumMetadata struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	ReleaseDate string `json:"release_date"`
+	TotalTracks int    `json:"total_tracks"`
+	Images      string `json:"images"`
+	AlbumType   string `json:"album_type"`
+	Artists     string `json:"artists"`
+}
+
+type ArtistResponsePayload struct {
+	ArtistInfo ArtistInfoMetadata    `json:"artist_info"`
+	Albums     []ArtistAlbumMetadata `json:"albums"`
+}
+
+type TrackResponse struct {
+	Track TrackMetadata `json:"track"`
+}
+
+type SearchArtistResult struct {
+	ID         string `json:"id"`
+	Name       string `json:"name"`
+	Images     string `json:"images"`
+	Followers  int    `json:"followers"`
+	Popularity int    `json:"popularity"`
+}
+
+type SearchAlbumResult struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	Artists     string `json:"artists"`
+	Images      string `json:"images"`
+	ReleaseDate string `json:"release_date"`
+	TotalTracks int    `json:"total_tracks"`
+	AlbumType   string `json:"album_type"`
+}
+
+type SearchPlaylistResult struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	Owner       string `json:"owner"`
+	Images      string `json:"images"`
+	TotalTracks int    `json:"total_tracks"`
+}
+
+type SearchAllResult struct {
+	Tracks    []TrackMetadata        `json:"tracks"`
+	Artists   []SearchArtistResult   `json:"artists"`
+	Albums    []SearchAlbumResult    `json:"albums"`
+	Playlists []SearchPlaylistResult `json:"playlists"`
+}

go_backend/mobile_deps.go

@@ -0,0 +1,8 @@
+// This file ensures gomobile dependencies are not removed by go mod tidy.
+// These packages are required by gomobile bind but not directly imported in code.
+
+package gobackend
+
+import (
+	_ "golang.org/x/mobile/bind"
+)

go_backend/output_fd.go

@@ -0,0 +1,88 @@
+package gobackend
+
+import (
+	"fmt"
+	"os"
+	"strings"
+)
+
+func isFDOutput(outputFD int) bool {
+	return outputFD > 0
+}
+
+func openOutputForWrite(outputPath string, outputFD int) (*os.File, error) {
+	if isFDOutput(outputFD) {
+		// Never hand the original detached FD directly to a provider attempt.
+		// Fallback chains may retry with another provider after a failure.
+		// If the first attempt closes the original FD, its numeric ID can be
+		// reused by unrelated resources and a later close may trigger fdsan abort.
+		dupFD, err := dupOutputFD(outputFD)
+		if err != nil {
+			return nil, fmt.Errorf("failed to duplicate output fd %d: %w", outputFD, err)
+		}
+		if err := prepareDupFDForWrite(dupFD, outputFD); err != nil {
+			_ = closeFD(dupFD)
+			return nil, err
+		}
+		return os.NewFile(uintptr(dupFD), fmt.Sprintf("saf_fd_%d_dup_%d", outputFD, dupFD)), nil
+	}
+
+	path := strings.TrimSpace(outputPath)
+	if strings.HasPrefix(path, "/proc/self/fd/") {
+		// Re-open procfs fd path instead of taking ownership of raw detached fd.
+		// Some SAF providers reject O_TRUNC on these descriptors with EACCES/EPERM.
+		file, err := os.OpenFile(path, os.O_WRONLY|os.O_TRUNC, 0)
+		if err == nil {
+			return file, nil
+		}
+		if strings.Contains(strings.ToLower(err.Error()), "permission denied") {
+			return os.OpenFile(path, os.O_WRONLY, 0)
+		}
+		return nil, err
+	}
+
+	return os.Create(outputPath)
+}
+
+func prepareDupFDForWrite(dupFD, originalFD int) error {
+	// Best-effort reset so retries start writing from byte 0.
+	if err := truncateFD(dupFD); err != nil {
+		if isBestEffortTruncateError(err) {
+			GoLog("[OutputFD] truncate not supported on fd %d (dup of %d): %v\n", dupFD, originalFD, err)
+		} else {
+			return fmt.Errorf("failed to truncate output fd %d (dup of %d): %w", dupFD, originalFD, err)
+		}
+	}
+	if err := seekFDStart(dupFD); err != nil {
+		GoLog("[OutputFD] seek reset failed on fd %d (dup of %d): %v\n", dupFD, originalFD, err)
+	}
+	return nil
+}
+
+func closeOwnedOutputFD(outputFD int) {
+	if !isFDOutput(outputFD) {
+		return
+	}
+
+	if err := closeFD(outputFD); err != nil {
+		if !isBadFD(err) {
+			GoLog("[OutputFD] failed to close detached fd %d: %v\n", outputFD, err)
+		}
+		return
+	}
+
+	GoLog("[OutputFD] closed detached fd %d\n", outputFD)
+}
+
+func cleanupOutputOnError(outputPath string, outputFD int) {
+	if isFDOutput(outputFD) {
+		return
+	}
+
+	path := strings.TrimSpace(outputPath)
+	if path == "" || strings.HasPrefix(path, "/proc/self/fd/") {
+		return
+	}
+
+	_ = os.Remove(path)
+}