Retreivr Browser Extensions

Shared browser-extension workspace for Retreivr.

Users should install prebuilt release bundles or marketplace versions, not run build commands themselves.

Targets

• Chrome
• Edge
• Brave
• Firefox
• Safari prep bundle

Install

See:

• Install Guide
• Release Guide
• Store Submission Prep

MVP

• detect likely media URLs on the active page
• show a Retreivr action only for sites/pages that can usually be handled by yt-dlp
• send the current URL to Retreivr Core for single-URL download
• open Retreivr UI from the popup/options page
• support right-click flows for:
  • page URL
  • link URL
  • video/audio source URL

Assumptions

• Retreivr Core is running and reachable from the browser
• Retreivr exposes a single-URL download endpoint or will be aligned to one
• initial UX is thin on purpose; the extension delegates work to core

Local build

npm run build

Outputs are written to dist/<browser>.

Release zips are produced by CI on version tags and can also be produced locally with:

npm run package:release

Load unpacked

Chromium browsers

Use the corresponding dist/chrome, dist/edge, or dist/brave directory as an unpacked extension.

Firefox

Load dist/firefox as a temporary add-on.

Safari

dist/safari is a prep bundle for Safari conversion, not a finished signed Safari extension. A later step should wrap this with the Safari Web Extension tooling.

Current endpoint assumption

This scaffold currently targets:

• POST /api/run

Request body:

{
  "single_url": "https://example.com/watch?v=123"
}

This matches the current core single-URL flow documented in api/README.md.

Current detection behavior

The scaffold currently recognizes:

• YouTube
• YouTube Music
• common media hosts such as SoundCloud, Vimeo, Rumble, Bandcamp, Twitch, TikTok, Instagram, X/Twitter, and Facebook
• generic URLs with media-like path hints such as /watch, /video, /playlist, /track, /album

YouTube normalization currently converts:

• youtu.be/... -> canonical youtube.com/watch?v=...
• /shorts/... -> canonical watch?v=...
• playlist URLs -> stripped to the canonical list=... form

Suggested next steps before a real public v0.1.0

• add better site-aware placement so the in-page button feels native on YouTube/YouTube Music
• add lightweight user feedback for queue success/failure from the core response
• confirm the Retreivr single-URL destination path behavior is correct for extension-originated jobs
• test on Chrome + Firefox first before treating Safari as production-ready

Icon assets

The repo now includes square PNG icon variants derived from the main Retreivr app icon:

• assets/icons/icon-16.png
• assets/icons/icon-32.png
• assets/icons/icon-48.png
• assets/icons/icon-128.png

These are the icon files used in generated extension manifests and are suitable for local packaging and initial store prep.

Versioning

• Source-of-truth version: package.json
• Human-readable release notes: CHANGELOG.md
• Tagged GitHub releases build prepackaged browser zip assets automatically