# Firefox Splice Download Helper

This Firefox extension captures Splice sample preview context from GraphQL responses, then attempts to download full-file URLs when available. If full retrieval is unavailable, it falls back to decoding preview audio bytes (splicedd-style) and downloads decoded MP3.

## Features

- Captures sample context from Splice GraphQL responses (`preview_mp3`, sample UUID/hash).
- Tracks observed audio sample URLs from network/probe fallback.
- Download action is orchestrated as:
  1. Attempt full-file URL retrieval first.
  2. If unavailable, decode scrambled preview bytes and download decoded MP3.
- Injects two controls in the target row:
  - **Download**: full-first, decoded-preview fallback
  - **History**: opens extension history page with past captured URLs
- Popup/history show each captured sample with source and mode hints.

## Targeted Page Element

Inline controls are injected into:

- `.playbar-playback-info-bar.playback-row-section.svelte-11gjrk3`

The inserted controls use sibling-style wrappers based on:

- `bordered-item meta-item svelte-11gjrk3`

## URL Rules

- Page scope: `*://*.splice.com/*`
- Audio sample paths include `/audio_samples/`
- Waveform files (`.wv.json`) are excluded from download candidates

## Load in Firefox (Temporary Add-on)

1. Open `about:debugging#/runtime/this-firefox`
2. Click **Load Temporary Add-on...**
3. Select this extension's `manifest.json`
4. Visit a matching `*.splice.com` page

## Usage

1. Open a page under `*.splice.com` that loads S3 audio links.
2. Wait for inline `Download` and `History` controls to appear in the playback info bar.
3. Click:
   - **Download** to run full-first retrieval, then decode fallback if needed
   - **History** to open full captured history
4. Optionally click the extension icon to open popup for current-tab entries.

## Manual Verification Checklist

- [ ] On matching domain, controls appear in target playback row.
- [ ] Controls remain after SPA/Svelte rerenders.
- [ ] GraphQL preview context is captured for visible samples.
- [ ] `Download` attempts full retrieval first.
- [ ] When full retrieval is unavailable, fallback decoded MP3 is downloaded and playable.
- [ ] `History` opens and allows downloading older entries.
- [ ] Popup updates with captured entries for active tab.
- [ ] Non-`*.splice.com` pages do not capture/store URLs.

## Known Limitations

- Full-file URL retrieval depends on backend behavior and session state; it may fail for some assets.
- Fallback decode uses scrambled preview streams, so fallback output follows preview-source quality/availability.
- Signed preview URLs can expire; expired URLs require recapture.
- `saveAs: true` prompts download location each time by design.