snap

docs/COMMERCIAL.md

@@ -0,0 +1,27 @@
+# Commercial features (developer-gated)
+
+Ads, in-app purchases, and Play Store helpers are **disabled for normal users**. Turn them on only in **Developer settings** while testing monetization.
+
+## Developer toggles
+
+| Setting | Effect |
+|---------|--------|
+| Enable in-app ads | Initializes `InAppAdCoordinator` (placeholder UI; AdMob not linked yet) |
+| Enable in-app purchases | Connects Google Play Billing; placeholder SKU `androidcast_premium` |
+| Enable Play Store integration | Allows listing intent + in-app review API |
+
+Changing a toggle calls `CommercialFeatures.refreshFromPreferences()`.
+
+## Before production
+
+1. Create app in **Google Play Console** and add in-app products matching `InAppPurchaseCoordinator.SKU_PREMIUM`.
+2. Add **AdMob** App ID to `AndroidManifest.xml` and replace `InAppAdCoordinator` placeholder with real ad units.
+3. Privacy policy + ads declaration if using ads.
+4. Remove or hide developer toggles in release builds (optional `BuildConfig.DEBUG` guard).
+
+## Code map
+
+- `com.foxx.androidcast.commercial.CommercialFeatures`
+- `InAppPurchaseCoordinator` — Billing Client 7.x
+- `InAppAdCoordinator` — stub
+- `PlayStoreIntegration` — `market://` + Play In-App Review

docs/ROADMAP.md

@@ -1,5 +1,75 @@
 # Android Cast — implementation roadmap
 
+Last updated: 2026-05-21. Living document — refine as alpha and commercial tracks progress.
+
+---
+
+## Alpha definition
+
+| Track | Goal | Status |
+|-------|------|--------|
+| **Android app** | Stable, feature-rich, **demo-ready** on LAN (discover → PIN → cast → stop; soak two devices) | Core path done; polish UX/docs and gate experimental options for show |
+| **Backend** | Deployed **OTA channel** + **crash ingest** (+ optional MQTT per `docs/OTA.md`) | WIP — examples under `examples/`; deployment blocked |
+
+**Alpha app** can ship before backend is live if the demo is LAN-only. **Full alpha** includes OTA/crash URLs configured in developer settings or `local.properties`.
+
+### Alpha app checklist
+
+- [ ] Happy path: UDP + H.264/AAC + single receiver, stream protection **None**
+- [ ] README matches `CastSettings` / `CastConfig` defaults
+- [ ] Fix misleading strings (e.g. camera “not implemented”)
+- [ ] Two-device QA script (rotate, background, notification stop)
+- [ ] Optional: cap multi-receiver at 1 for show, or soak 1:N
+
+### Alpha backend checklist
+
+- [ ] Host `examples/ota/v0/` channel JSON + APK artifacts
+- [ ] Deploy `examples/crash_reporter/backend/` (see `nginx.conf`, `README.md`)
+- [ ] Set `ota.channel.url` and crash upload URL in dev settings / `local.properties`
+
+---
+
+## Product positioning
+
+- **Primary:** Wi‑Fi LAN cast when **USB-C→HDMI** wired mirror fails or is unavailable (common on some tablets).
+- **Not in scope for v0:** Internet relay (`gateway_url_hint`), TLS on cast protocol, WebRTC as default transport.
+
+See [USB_HDMI_CAST.md](USB_HDMI_CAST.md) for wired display vs Wi‑Fi cast.
+
+---
+
+## USB-C / HDMI (roadmap D) and USB-tether cast (roadmap E)
+
+| Item | Status |
+|------|--------|
+| `WiredDisplayMonitor` — detect external displays | Done |
+| `ExternalDisplayCapturePolicy` + developer UI | Done (policy stored; capture still default display) |
+| `ScreenCastService` display hot-plug hooks | Done |
+| Secondary-display MediaProjection capture | TODO |
+| `UsbTetherCastTransport` stub + dev-gated transport id | Done |
+| USB tether / ADB reverse discovery + framing | TODO |
+
+Details: [USB_HDMI_CAST.md](USB_HDMI_CAST.md).
+
+---
+
+## Commercial (Play Store prep)
+
+All **off by default**. Enable only in **Developer settings** for internal testing.
+
+| Item | Status |
+|------|--------|
+| `CommercialFeatures` gate | Done |
+| `InAppPurchaseCoordinator` (Play Billing 7.x) | Done (connects when dev IAP on; SKU placeholder) |
+| `InAppAdCoordinator` (placeholder, no AdMob SDK yet) | Done |
+| `PlayStoreIntegration` (listing intent + in-app review API) | Done |
+| AdMob / unit IDs / banner layouts in main UI | TODO |
+| Play Console products + privacy policy | TODO |
+
+See [COMMERCIAL.md](COMMERCIAL.md).
+
+---
+
 ## Stream protection (FEC / NACK)
 
 | Item | Status |
@@ -17,6 +87,8 @@
 
 Enable in **Settings → Stream protection (UDP)** on both sender and receiver, then reconnect.
 
+---
+
 ## libvpx / Opus / Speex
 
 | Item | Status |
@@ -30,3 +102,48 @@ Enable in **Settings → Stream protection (UDP)** on both sender and receiver,
 | Opus / Speex build + sinks | TODO |
 
 See [ndk/README.md](../ndk/README.md).
+
+---
+
+## Transports & protocols
+
+| Transport | Status |
+|-----------|--------|
+| UDP (default) | Done |
+| TCP | Done |
+| QUIC (Cronet, experimental) | Partial |
+| WebRTC | Stub (`WebRtcCastTransport`) |
+| USB tether (`usb_tether`) | Stub — dev settings only |
+
+---
+
+## Receiver / sender UX
+
+| Item | Status |
+|------|--------|
+| `ReceiverPlaybackActivity` (primary receiver UI) | Done |
+| Settings drawer + themes + RU locale | Done |
+| Multi-receiver 1:N | Done (soak or gate for alpha) |
+| Legacy `ReceiverActivity` in manifest | Orphan — remove or wire |
+| Immersive A/V presets (dev) | Experimental |
+
+---
+
+## Deferred / post-alpha
+
+- Internet relay gateway
+- TLS on cast stream
+- Passthrough video codec
+- Lab automation under simulated loss
+- Full wired-HDMI capture (roadmap D phase 2)
+- USB-tether cast production path (roadmap E)
+
+---
+
+## Related docs
+
+- [README.md](../README.md) — quick start
+- [USB_HDMI_CAST.md](USB_HDMI_CAST.md) — D & E
+- [COMMERCIAL.md](COMMERCIAL.md) — ads / IAP / Play
+- [OTA.md](OTA.md) — backend layout v0
+- [CRASH_REPORTER.md](CRASH_REPORTER.md) — crash upload

docs/USB_HDMI_CAST.md

@@ -0,0 +1,51 @@
+# USB-C / HDMI and USB-tether cast (roadmap D & E)
+
+Android Cast streams over **Wi‑Fi** (UDP/TCP/QUIC). USB-C→HDMI adapters use Android’s **wired external display** stack, which is separate from the cast protocol.
+
+## Layer model
+
+| Layer | Mechanism | This app today |
+|-------|-----------|----------------|
+| Wired mirror | `DisplayManager` + HDMI/DP alt mode | Not encoded by us; OS drives the sink |
+| Wi‑Fi cast | MediaProjection + `CastTransport` | Primary product path |
+| USB-tether cast (E) | IP over USB (RNDIS/ADB reverse) + same framing | **Stub** (`usb_tether` transport) |
+
+## Phase D — external display awareness & future capture
+
+**Implemented (foundation):**
+
+- `WiredDisplayMonitor` — tracks non-default displays (HDMI, presentation, etc.).
+- `ExternalDisplayCapturePolicy` — developer preference for future capture routing.
+- Developer settings: live wired-display status + capture policy selector.
+- `ScreenCastService` registers extended display listener (rotation + hot-plug).
+
+**Not implemented yet (post-alpha):**
+
+- Capture **secondary display** via `MediaProjection` / `createVirtualDisplay` on non-default `Display`.
+- Android 14+ per-app capture rules and extend-vs-mirror modes.
+- Automatic switch to external display when passive/active USB-C adapter works.
+
+**User workaround when HDMI dongle fails:** LAN cast to a receiver (phone/box) connected to the projector by HDMI or built-in Android on the projector.
+
+## Phase E — USB-tether transport
+
+**Implemented (foundation):**
+
+- `UsbTetherCastTransport` stub implementing `CastTransport`.
+- `CastConfig.TRANSPORT_USB_TETHER` — selectable only when **Developer settings → USB-tether transport** is on.
+- Factory routes to stub; connect/listen throw until RNDIS/ADB tunnel + discovery are wired.
+
+**Future work:**
+
+- Detect USB tether / ADB TCP forward (`adb reverse`).
+- Optional discovery on `127.0.0.1` or tether interface IP.
+- Same `CastProtocol` framing as UDP/TCP.
+
+## Tablet + adapter checklist (e.g. Doogee Tab G6 Max → HY300)
+
+1. **Settings → Display** — does a second screen appear when the dongle is plugged in?
+2. **Passive** adapter: requires USB-C **DisplayPort Alt Mode** on the tablet port.
+3. **Active** adapter: needs a chip/firmware pair the tablet supports (often still DP alt mode internally).
+4. If the OS never sees an external display, **no app feature** can fix the cable path; use Wi‑Fi cast or receiver-on-HDMI.
+
+See [ROADMAP.md](ROADMAP.md) for alpha and commercial tracks.