merge: lane/ext

docs/05-extension-spec.md

@@ -162,4 +162,34 @@ extension/
 
 `<all_urls>` is unavoidable for a download manager but is the main review-friction item:
 document *why* in the AMO submission notes and in the source, and make the exclusion list
-prominent in Options.
+prominent in Options. The submission-ready copy of this table lives in
+`extension/docs/amo-permissions.md`, committed alongside the manifest it explains.
+
+## 8. Popup and Options talk to the background page over a relay, not directly
+
+`popup/` and `options/` are separate documents (a browser action popup and an
+`options_ui` page) — they cannot import `background/index.ts`'s live `VeloxTransport`.
+`background/bridge.ts` relays it over one `browser.runtime.connect` port per document:
+`call`/`subscribe`/`getStatus`/`reconnect`/`pair`/`unpair`/`setOverride` requests in,
+`result`/`event`/`status`/`pairError` responses out. `shared/panel-client.ts` is the
+client side both surfaces use. The status payload carries `kind` (which transport
+implementation is live) alongside the existing `TransportStatus`, because Options needs
+it: `settings.set` and `rules.upsert` are privileged, uds-only methods (see
+`shared/protocol/methods.ts`'s `METHODS` table), so the capture-policy edit form only
+ever unlocks when the active transport is native messaging. Over WebSocket — the
+default, guaranteed path per ADR 0003 — Options renders the daemon's policy read-only
+via `capture.getRules` rather than pretending it can write settings the protocol
+refuses over that transport. The one Options setting that genuinely belongs to the
+extension (not the daemon) — the default category applied to extension-initiated
+downloads — lives in `browser.storage.local` via `options/prefs.ts`, the same place the
+pairing token and transport override already live.
+
+Streaming-media detection (build step 7) also splits down this line: `capture/media.ts`
+(background, webRequest-based) recognizes `.m3u8`/`.mpd` URLs and their content types
+and tells the tab's content script over `runtime.sendMessage`
+(`background/media-bridge.ts`); `content/media-observer.ts` independently watches the
+page's own `<video>` elements for the same signal. Either one showing up opens
+`content/video-panel.ts`'s "Download this video ▾" panel, which calls
+`media.listVariants`/`media.addVariant` through the background page and greys out any
+variant (or the whole manifest) flagged `drm`/`drmProtected` with "Protected content" —
+the extension never parses the manifest itself.