From 6f06ea73d18f41c8dbec94ae7e7cf3fc61c6dc37 Mon Sep 17 00:00:00 2001
From: David Keane <david@davidtkeane.com>
Date: Tue, 9 Jun 2026 01:15:28 +0100
Subject: [PATCH] docs: 1000-char Single Purpose + permission justifications
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

David's first-pass through the Dashboard revealed that the
Single Purpose field, and each permission justification field,
have a 1000-char cap (not the much smaller cap I had assumed
from looking at older Web Store docs). Rewrote each to use
roughly 900 chars of the budget — gives reviewers the technical
detail they need to verify the code matches the claims.

- Single Purpose (970 chars) — 3 numbered things the extension does,
  what it explicitly does not do (no SDK, no analytics, no remote).
- offscreen (976 chars) — why MV3 needs offscreen for audio, with
  the developer.chrome.com pointer for the reviewer to verify.
- storage (867 chars) — per-key inventory + Options-page wipe path
  + privacy policy URL for cross-reference.
- somafm.com host (910 chars) — exact endpoints listed, what we
  do NOT send with the requests, SomaFM's community-friendly stance.
- Added: 'I am not using remote code' note for the cert checkbox.
---
 WEB_STORE_SUBMISSION.md | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/WEB_STORE_SUBMISSION.md b/WEB_STORE_SUBMISSION.md
index eb708de..9a2b7fb 100644
--- a/WEB_STORE_SUBMISSION.md
+++ b/WEB_STORE_SUBMISSION.md
@@ -20,9 +20,9 @@ Everything you need to paste into the Chrome Web Store Developer Dashboard when
 
 ## 1. Single purpose statement
 
-(Dashboard → Privacy practices → Single purpose. Be specific — vague descriptions get rejected.)
+(Dashboard → Privacy practices → Single purpose. Be specific — vague descriptions get rejected. Field is 1000-char limit — copy below is 970 chars.)
 
-> Plays internet radio streams from SomaFM in the browser, logs the tracks you have heard while listening, and provides public-search link-outs to Spotify, YouTube, Apple Music, and Bandcamp so you can find any track on your preferred music service.
+> 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.
 
 ---
 
@@ -106,19 +106,23 @@ The Dashboard's Privacy Practices tab is the surface that gets compared three wa
 
 ## 7. Permission justifications
 
-(Dashboard → Privacy practices → Permission justifications. Each must explain WHY the permission is needed in 1–2 sentences. Reviewers compare these to the actual code.)
+(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`
+### `offscreen` (976 chars)
 
-> Manifest V3 service workers cannot host an `<audio>` element. RangerHQ Tuner uses `chrome.offscreen.createDocument({reasons: ['AUDIO_PLAYBACK']})` to create a hidden document that plays the SomaFM stream. Required by Chrome's architecture; no user data passes through this surface.
+> 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`
+### `storage` (867 chars)
 
-> Persists the user's last-played station, volume preference, configurable history cap, track history, and favourites in `chrome.storage.local` on the user's own device. No data is ever transmitted off-device.
+> 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/*`)
+### Host permission `https://somafm.com/*` and `https://*.somafm.com/*` (910 chars)
 
-> Fetches the public SomaFM station catalogue (`channels.json`), the per-station playlist files (`.pls`), the live audio streams, and the public now-playing track metadata. SomaFM is the radio source the extension plays. No authentication, no user identifiers, no analytic parameters — only standard public-API calls.
+> 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.
 
 ---