Working

README.md

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