rangerhq-tuner/WEB_STORE_SUBMISSION.md

# Chrome Web Store Submission Notes — RangerHQ Tuner v0.3.0

Everything you need to paste into the Chrome Web Store Developer Dashboard when submitting. Reference for filling the form — not part of the extension ZIP.

---

## 0. Pre-flight checklist

- [ ] Signed in to **https://chrome.google.com/webstore/devconsole** as `david@davidtkeane.com`
- [ ] 2-Step Verification active on the Google account ✅ (already done per David, 2026-06-09)
- [ ] $5 one-time developer registration fee paid (USD; first-time only)
- [ ] Privacy policy published at **https://davidtkeane.com/rangerhq-tuner/privacy**
- [ ] Landing page live at **https://davidtkeane.com/rangerhq-tuner/**
- [ ] Build the submission ZIP (see §9 below)
- [ ] Screenshots captured (1280×800 PNG, 1–5 images) — deferred per David
- [ ] Promo tile (440×280 PNG) — deferred per David
- [ ] Submit Tuesday-Thursday morning Dublin time (Wed-Fri midnight onwards US time = best window)

---

## 1. Single purpose statement

(Dashboard → Privacy practices → Single purpose. Be specific — vague descriptions get rejected. Field is 1000-char limit — copy below is 970 chars.)

> RangerHQ Tuner is a lightweight browser-resident internet radio player for SomaFM, a listener-supported indie radio network. The extension does three things: (1) plays SomaFM audio streams directly from the browser toolbar popup and an optional New Tab Page; (2) logs a capped FIFO history of the artist and title of each track that plays, so the user can revisit anything they heard later; (3) provides four public-search link-outs per history entry — Spotify, YouTube, Apple Music, and Bandcamp — that open in a new browser tab so the user can find the track on their preferred music service. The extension does not embed any third-party SDK, player, or analytics. The four service buttons are plain HTML anchor tags pointing at each service's public search URL. Audio is hosted in a Chrome offscreen document because Manifest V3 service workers cannot host audio elements. No accounts, no telemetry, no remote storage; all state lives in chrome.storage.local.

---

## 2. Short description (132 characters max)

(Dashboard → Store listing → Summary. Mine is 130 chars — tight.)

> Lightweight SomaFM radio player. Logs what plays. One-click search to Spotify, YouTube, Apple Music, Bandcamp. No telemetry.

---

## 3. Detailed description (~1500 chars)

(Dashboard → Store listing → Description.)

> **RangerHQ Tuner** is a lightweight indie internet radio player that lives in your Chrome toolbar. It plays SomaFM's listener-supported indie radio network and logs every track that comes through so you can find your favourites later.
>
> ✦ **Toolbar player** — click the helmet icon, pick a station, music starts. Audio keeps playing after the popup closes.
> ✦ **New Tab Page** — every new tab becomes a Tuner landing with live clock, station picker, history, and favourites. (Optional; replaces Chrome's default new tab.)
> ✦ **Track history** — RangerHQ Tuner logs the artist and title of every track that plays on SomaFM, up to 500 tracks (configurable 50–500).
> ✦ **One-click search to the big four** — next to every history entry, four buttons open public search results in a new tab: **Spotify**, **YouTube**, **Apple Music**, and **Bandcamp**. No accounts, no API keys, no Premium required. You find the track; the destination service plays it.
> ✦ **Favourites** — star any heard track to keep it forever.
> ✦ **Settings page** — clear history, clear favourites, clear everything, adjust the history cap, see how much local storage RangerHQ Tuner is using.
>
> **Privacy**
> RangerHQ Tuner collects no personal data. Nothing leaves your device. All history, favourites, and settings live in `chrome.storage.local` on your own machine. The only external server contacted is SomaFM's public API. No telemetry, no analytics, no third-party SDKs. Full policy: https://davidtkeane.com/rangerhq-tuner/privacy
>
> **Open source**
> GPL v2 or later. Source: https://git.davidtkeane.com/ranger/rangerhq-tuner
>
> **Family**
> Sibling to RangerHQ Radio for WordPress: https://wordpress.org/plugins/rangerhq-radio/

---

## 4. Category

**Productivity** (primary) — same category as the other browser-resident utility players.

Alternatives if Productivity feels off: **Fun** or **News & Weather** — but Productivity is the cleanest fit for a quiet always-on tool.

---

## 5. Language

**English (United Kingdom)** as the primary listing language.

---

## 6. Privacy practices section (the critical match)

The Dashboard's Privacy Practices tab is the surface that gets compared three ways: manifest permissions ↔ Dashboard declarations ↔ public privacy policy. **Any mismatch = auto-rejection** (per `~/.ranger-memory/docs/WP_ORG_SUBMISSION_CHECKLIST.md` lesson on the equivalent rule). Match all three.

### 6.1 Data collection — answer for every category

| Category | Tick this answer |
|---|---|
| Personally identifiable information | **Does not collect** |
| Health information | **Does not collect** |
| Financial and payment information | **Does not collect** |
| Authentication information | **Does not collect** |
| Personal communications | **Does not collect** |
| Location | **Does not collect** |
| Web history | **Does not collect** |
| User activity | **Does not collect** |
| Website content | **Does not collect** |

### 6.2 Data usage certifications — tick ALL THREE boxes

- [x] I do not sell or transfer user data to third parties, outside of the approved use cases.
- [x] I do not use or transfer user data for purposes that are unrelated to my item's single purpose.
- [x] I do not use or transfer user data to determine creditworthiness or for lending purposes.

### 6.3 Privacy policy URL

> **https://davidtkeane.com/rangerhq-tuner/privacy**

(Live before submission. Public, no login required.)

---

## 7. Permission justifications

(Dashboard → Privacy practices → Permission justifications. Each field has a 1000-char limit. All three below are pre-counted under the cap. Reviewers compare these against the actual code, so don't paraphrase — paste verbatim.)

### `offscreen` (976 chars)

> The offscreen permission is required because Manifest V3 service workers cannot host an HTML audio element. Service workers in MV3 are killed by Chrome whenever they go idle, which would cause audio playback to stop randomly. The Chrome offscreen API (chrome.offscreen.createDocument) is the official Manifest V3 mechanism for creating a hidden DOM document that can host long-lived audio. RangerHQ Tuner creates a single offscreen document with reason AUDIO_PLAYBACK to hold the audio element that plays the SomaFM stream. The offscreen document is created lazily on the first user-initiated play and persists for the rest of the browser session, then is destroyed when the extension is unloaded. No user data passes through this surface; it only proxies audio control messages (play, pause, set volume) from the popup and New Tab Page UI to the audio element. The offscreen API is the only supported pattern for persistent audio in Manifest V3, per developer.chrome.com.

### `storage` (867 chars)

> The storage permission is required to persist a small amount of user-facing state in chrome.storage.local on the user's own device. RangerHQ Tuner stores: the user's last-played station ID, the current volume level, a configurable history cap, a 6-hour cache of the SomaFM station catalogue, a capped FIFO list of the artist and title of recently played tracks (default 500, user-configurable 50 to 500), and a list of user-starred favourite tracks. All data lives in chrome.storage.local and never leaves the user's device. No data is sent to the extension author, Google, or any third party. The user can wipe any or all of this data at any time from the extension's Options page (Clear history, Clear favourites, and Clear EVERYTHING buttons). The full per-key inventory is published in the extension's privacy policy at davidtkeane.com/rangerhq-tuner/privacy.

### Host permission `https://somafm.com/*` and `https://*.somafm.com/*` (910 chars)

> The somafm.com host permission is required to fetch the public SomaFM station catalogue (channels.json), per-station playlist files (.pls), the live audio streams, and the public now-playing track metadata (songs/{id}.json). SomaFM is the radio source the extension plays. These API endpoints are publicly accessible with no authentication required. RangerHQ Tuner does not send any user identifiers, tracking parameters, authentication tokens, or analytics data with these requests; only standard public HTTP calls. The user's IP address is naturally observable by SomaFM as part of routine HTTP serving, exactly the same as if the user visited somafm.com in a browser tab. No data flows from the user to anywhere other than SomaFM through this permission. SomaFM is a listener-supported independent radio network whose community guidelines explicitly welcome third-party tools playing their public streams.

### Remote code use

> **Tick: "I am not using remote code."** No `eval`, no dynamically loaded scripts, no fetched-then-executed JavaScript. Every line of code that runs ships inside the submitted package.

---

## 8. Distribution

- **Visibility:** Public
- **Geographic distribution:** All regions
- **Pricing:** Free

---

## 9. Building the submission ZIP

From the extension root (`~/scripts/chrome-extensions/rangerhq-tuner/`):

```bash
cd ~/scripts/chrome-extensions/rangerhq-tuner
zip -r ~/Desktop/rangerhq-tuner-v0.3.0.zip \
  manifest.json \
  src/ \
  LICENSE \
  -x "*.DS_Store" \
  -x "*/.git/*" \
  -x "*/node_modules/*"
ls -lh ~/Desktop/rangerhq-tuner-v0.3.0.zip
```

(`README.md`, `CHANGELOG.md`, `PRIVACY.md`, `WEB_STORE_SUBMISSION.md`, the `.git` directory, and `.DS_Store` files are deliberately excluded — they are repo artefacts, not user-facing extension files.)

---

## 10. Screenshot brief (when you're ready)

5 screenshots at **1280×800 PNG** would be ideal. Suggestions, in order of impact:

1. **Toolbar popup playing a station** — helmet icon visible in the toolbar, popup open showing Now Playing, controls, and the search list. Background should be a normal-looking webpage (your own blog?) so the reviewer sees the popup in context.
2. **New Tab Page with the player + history** — the full landing with clock top right, current track centred, History tab selected, ~5 tracks visible with the 4 search buttons.
3. **Favourites tab** — same NTP layout but the Favourites tab selected, a few stars filled in.
4. **Options page** — showing the stats card, history cap slider mid-range, the three Clear buttons.
5. **Quick stations chip row** + a SomaFM station closeup — emphasises the "30 channels in one click" angle.

### Promo tile (440×280 PNG)

A clean composition: helmet on the left, "RangerHQ Tuner" in your brand font on the right, optionally with a smaller tagline ("Indie radio, in your toolbar"). Dark background `#1a221c`. Accent green `#6dbf7a` for the typography.

### Marquee tile (1400×560 PNG, optional)

Same as promo tile but wider — adds a screenshot of the NTP on the right half. Optional but Google promos extensions with marquee assets more often.

---

## 11. After approval — SVN-equivalent for Chrome

Unlike wp.org (which uses SVN for plugins), Chrome Web Store updates go through the same Developer Dashboard:

1. Bump `manifest.json` version (`0.3.0` → `0.3.1` or `0.4.0`).
2. Update `CHANGELOG.md`.
3. Tag the Gitea release: `git tag -a v0.3.1 -m "..." && git push origin v0.3.1`.
4. Build a fresh ZIP (same command as §9 with the new version).
5. Dashboard → RangerHQ Tuner → Package → Upload new package → Submit.
6. Update review: typically 24–48 hours per [[reference_chrome_web_store_rules]].

The extension ID stays the same forever (it's bound to the first signing certificate Google generates). Future updates just need a higher version.

---

## 12. Quick links

- **Dev Console:** https://chrome.google.com/webstore/devconsole
- **Program policies:** https://developer.chrome.com/docs/webstore/program-policies/policies
- **Privacy policy requirements:** https://developer.chrome.com/docs/webstore/program-policies/privacy
- **Best practices:** https://developer.chrome.com/docs/webstore/program-policies/best-practices

— Notes maintained at `WEB_STORE_SUBMISSION.md` in the repo. Updated for v0.3.0 on 2026-06-09.