Merge pull request #165 from doublegate/feat/v1.8.7-connectivity-completion

v1.8.7 "Android" — Connectivity completion (CGNAT netplay + controllers)

Author: doublegate

CHANGELOG.md

@@ -15,6 +15,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.7] - 2026-06-20 - "Android" (Connectivity completion)
+
+Completes v1.8.6's connectivity work: **CGNAT / TURN room-code netplay** so phones on
+cellular (symmetric-NAT) networks can play, plus a **robust hardware-controller** input
+pipeline (wired USB + Bluetooth), a **controller-aware UI**, and **Chromecast prep**
+behind a default-off flag. Additive and host-side only — the emulation core stays
+byte-identical, so **AccuracyCoin holds 100% (139/139)** on host CI and the desktop is
+unchanged. This is a sideload-only / GitHub-Releases build (`PLAY_BUILD=false`); the
+Google Play launch moves to **v1.8.8 "Atlas"**.
+
+### Added
+
+- **CGNAT / TURN room-code netplay.** A `NatConnect` orchestrator (STUN discovery →
+  UDP hole-punch → a relay fallback for symmetric NAT) drives a `Registering →
+  Discovering → Exchanging → Punching → (Relaying) → Synced` pump, exchanging each
+  peer's public address via a new `SignalMessage::PublicAddr` routed over the same
+  `signaling::Relay` as browser SDP. The bridge gains `np_host_room` / `np_join_room`
+  (a host emits a deterministic 6-char room code; a peer joins by code), and the
+  Android UI adds an **"Online (room code)"** mode beside the v1.8.6 LAN Host/Join —
+  share the code, join by code, and watch the Registering / Punching / Relaying
+  progress. For symmetric NAT the relay-transport hand-off (`is_relayed`) routes the
+  whole GGPO session over the TURN relay via an `RelayUdpSocket` shim, so
+  `RollbackSession` stays a single transport type. The blocking `tungstenite`
+  signaling client cross-compiles with no tokio. Verified in-process via
+  `nat_loopback` (hole-punch) and `relay_loopback` (a mock RFC 8656 TURN relay,
+  90-frame confirmed-digest parity). The live cross-NAT path needs the maintainer's
+  hosted `deploy/` relay + two devices (carryover); the placeholder signaling URL is
+  overridable in Settings.
+- **Robust hardware controllers (wired USB + Bluetooth).** The Android input pipeline
+  is overhauled from "P1 buttons only" to full pad support: a new `onGenericMotionEvent`
+  handler (previously absent, so analog sticks and the d-pad-as-HAT axis silently
+  failed on 8BitDo / DualSense / OTG pads) reads `AXIS_HAT_X/Y`, sticks past the
+  reported dead-zone, and triggers; per-port P1–P4 masks with `InputManager` hot-plug
+  (auto Four Score at ≥ 3 pads); per-descriptor remapping persisted as JSON keyed by
+  `InputDevice.getDescriptor()`; and turbo / autofire. No Rust change — the bridge
+  already exposed `setButtons(port, …)` + `setFourScore`.
+- **Controller-aware UI.** Connecting a hardware controller hides the on-screen virtual
+  controller and maximizes the ROM display (8:7 PAR, valuable on the Z Fold 7 inner
+  screen); disconnecting restores it. The **Guide** button (best-effort,
+  `KEYCODE_BUTTON_MODE`) or **Start + Select** (guaranteed) opens a controller-navigable
+  menu driven by the d-pad + A/B.
+- **Chromecast prep.** A CAF sender (`ChromecastSender` + a `MediaRouteButton`) and a
+  static Web Receiver render a ~20–30 fps spectator mirror, gated behind a default-off
+  `CHROMECAST_ENABLED` BuildConfig flag — when off the sender is dead code and behaviour
+  is unchanged; the low-latency **Presentation API** stays the primary cast path. The
+  frame is down-sampled to a 128×120 6-bit index plane (~20.5 KB) under the CAF message
+  cap. AirPlay was researched and skipped (no maintained FOSS sender; FairPlay / legal).
+  Live use needs the maintainer's Cast App ID + an HTTPS-hosted receiver (carryover).
+
 ## [1.8.6] - 2026-06-20 - "Android" (Connectivity & scripting)
 
 The connectivity & scripting pass: **Lua**, **RetroAchievements**, and **Netplay** on

Cargo.lock

@@ -19,7 +19,7 @@ members = [
 ]
 
 [workspace.package]
-version = "1.8.6"
+version = "1.8.7"
 edition = "2024"
 rust-version = "1.96"
 license = "MIT OR Apache-2.0"

Cargo.toml

@@ -10,7 +10,7 @@
 
 [![Build Status](https://github.com/doublegate/RustyNES/workflows/CI/badge.svg)](https://github.com/doublegate/RustyNES/actions)
 [![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)
-[![Version](https://img.shields.io/badge/version-v1.8.6-blue.svg)](https://github.com/doublegate/RustyNES/releases)
+[![Version](https://img.shields.io/badge/version-v1.8.7-blue.svg)](https://github.com/doublegate/RustyNES/releases)
 [![Rust: 1.96](https://img.shields.io/badge/rust-1.96-orange.svg)](rust-toolchain.toml)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20Web-lightgrey.svg)](#platform-support)
 [![AccuracyCoin](<https://img.shields.io/badge/AccuracyCoin-100%25%20(139%2F139)-brightgreen.svg>)](#compatibility-and-accuracy)
@@ -645,16 +645,18 @@ workspace API docs (rustdoc) at
 
 ## Version History
 
-The current release is **v1.8.6 "Android"**, continuing the first **platform** (not
+The current release is **v1.8.7 "Android"**, continuing the first **platform** (not
 accuracy) release line **v1.8.0 "Android"** — a complete Android app, verified
 end-to-end on a Samsung Galaxy Z Fold 7. It builds on the bugfix patch **v1.7.1** and
 the writable + programmable **v1.7.0 "Forge"** line, on the cycle-accurate v1.0.0
-production core. (v1.8.6 makes the Android app feature-complete — **Lua**,
-**RetroAchievements**, and **netplay** — and gates the **Google Play launch** as its
-capstone; v1.8.0–v1.8.6 are GitHub-Releases / sideload, full-featured.) The road so far:
+production core. (v1.8.7 completes the connectivity work — **CGNAT / TURN room-code
+netplay**, robust **hardware controllers**, and a controller-aware UI — atop the
+feature-complete v1.8.6; v1.8.0–v1.8.7 are GitHub-Releases / sideload, full-featured.
+The **Google Play launch** moves to **v1.8.8 "Atlas"**.) The road so far:
 
 | Version    | Highlights                                                                                  |
 | ---------- | ------------------------------------------------------------------------------------------- |
+| **v1.8.7** | "Android" — connectivity completion. **CGNAT / TURN room-code netplay** completes v1.8.6's direct-IP / LAN netplay: a **`NatConnect`** orchestrator (STUN discovery → UDP hole-punch → a `SignalMessage::PublicAddr` exchange over the same `signaling::Relay` → a **TURN relay fallback** for symmetric NAT, `is_relayed`) with `np_host_room` / `np_join_room` bridge methods and an **"Online (room code)"** Android UI (share a 6-char code, join by code, Registering / Punching / Relaying progress + a "via relay" badge). Plus **robust hardware controllers** (the input pipeline gains `onGenericMotionEvent` — analog sticks + the d-pad-as-HAT axis silently failed on 8BitDo / DualSense / OTG pads before — with per-port P1–P4 masks, `InputManager` hot-plug, per-descriptor remapping, and turbo / autofire; no Rust change), a **controller-aware UI** (connect a pad → the on-screen controller hides + the ROM display maximizes; Guide or Start + Select opens a d-pad-navigable menu), and **Chromecast prep** behind a default-off `CHROMECAST_ENABLED` flag (a CAF sender + a static Web Receiver spectator mirror; the Presentation API stays primary). Loopback / mock-verified; live cross-NAT + the hosted relay are maintainer carryovers. All host-side; AccuracyCoin holds 100% (139/139). Sideload-only — the **Google Play launch** is **v1.8.8 "Atlas"**. |
 | **v1.8.6** | "Android" — connectivity & scripting. **Lua** (the sandboxed desktop engine over the bridge — made `Send`; SAF `.lua` load + an on-screen log overlay), **RetroAchievements** (login + hardcore + unlock toasts + a `.rap` progress sidecar; the session extracted into a new shared **`rustynes-ra`** crate, `ureq` + `rustls` + `ring` TLS — no OpenSSL), and **direct-IP / LAN netplay** (GGPO rollback over `rustynes-netplay`; the loop calls `np_advance_frame` instead of `run_frame` while connected), plus an **Open / Close ROM** toggle. The shared `rustynes-mobile` bridge is now connectivity-complete, so **v1.9.0 iOS inherits all three**. All host-side; AccuracyCoin holds 100% (139/139). The **Google Play launch** (`$2.99` Full Unlock) is the decoupled capstone; CGNAT/TURN netplay is deferred to v1.8.7. |
 | **v1.8.5** | "Android" — power-user features. **Custom `.pal` palettes** + **compressed `.zip` ROM loading** (extract the first NES entry, like desktop); **Bisqwit composite NTSC on the GPU** (the desktop WGSL shared via `rustynes-gfx-shaders`, an `R16Uint` palette-index pipeline fed by the bridge); **TAS `.rnm` movies** (record / play / save via SAF, determinism-exact); a **per-game settings DB** (each game reopens with its last video filter, keyed by ROM SHA); and **HD-packs on Android** — the HD-pack loader + compositor + HD audio were **extracted into a new shared `rustynes-hdpack` crate** (the core is `#![no_std]`) so the bridge can composite the upscaled picture (Bitmap path). All presentation / host-side; AccuracyCoin holds 100% (139/139). |
 | **v1.8.4** | "Android" — native wgpu renderer & shaders. The NES picture now draws through **wgpu on a `SurfaceView`** (Vulkan/GLES) instead of the Compose `Bitmap` blit, reusing the desktop WGSL: a shared **`rustynes-gfx-shaders`** crate serves the **CRT / scanline + LMP88959 NTSC** post-passes to both desktop and Android, with **per-filter tuning sliders** (intensity / count / mask / saturation / sharpness …) and a native-audio hot path (bytes, no boxing). Opt-in behind a "GPU renderer" setting (API 33+); the Bitmap path stays the fallback. |
@@ -797,7 +799,7 @@ If you use RustyNES in academic research, please cite:
   author  = {RustyNES Contributors},
   title   = {RustyNES: A Cycle-Accurate NES Emulator in Rust},
   year    = {2026},
-  version = {1.8.6},
+  version = {1.8.7},
   url     = {https://github.com/doublegate/RustyNES},
   note    = {Cycle-accurate NES emulator on a master-clock-precise scheduler;
              AccuracyCoin 100\% (139/139), nestest 0-diff; 168 mapper families,

README.md

@@ -30,15 +30,24 @@ android {
         applicationId = "com.doublegate.rustynes"
         minSdk = 26 // AAudio floor.
         targetSdk = 35 // Play mandate since 2025-08-31.
-        versionCode = 10806 // 1.8.6
-        versionName = "1.8.6"
+        versionCode = 10807 // 1.8.7
+        versionName = "1.8.7"
         // No abiFilters here — set per buildType so release ships arm64 only
         // while debug keeps x86_64 for the emulator.
         // PLAY_BUILD gates the freemium (demo timer + persistence locks + Billing).
         // Default false → sideload/GitHub/dev builds are full-featured; the Google
-        // Play AAB sets it true (v1.8.6 launch). See the v1.8.0 plan's monetization
-        // timing.
+        // Play AAB sets it true (v1.8.8 "Atlas" launch — postponed from v1.8.6). See
+        // the v1.8.0 plan's monetization timing.
         buildConfigField("boolean", "PLAY_BUILD", "false")
+        // CHROMECAST_ENABLED gates the experimental Cast Application Framework
+        // (CAF) sender path (v1.8.7, #38) — a ~20-30fps SPECTATOR mirror to a
+        // custom Web Receiver, distinct from the primary low-latency Presentation
+        // API cast (Cast.kt, which is always available). Default false: no Cast
+        // button, no CastContext init, zero behavior change. It stays off until the
+        // maintainer does the deferred ops (a $5 Cast Developer Console account, a
+        // registered Receiver App ID, and HTTPS hosting of android/cast-receiver/).
+        // See android/cast-receiver/README.md + ChromecastSender.kt.
+        buildConfigField("boolean", "CHROMECAST_ENABLED", "false")
     }
 
     // Release signing reads `keystore.properties` (gitignored) or env vars; when
@@ -152,6 +161,8 @@ dependencies {
     implementation("androidx.core:core-ktx:1.15.0")
     implementation("androidx.activity:activity-compose:1.9.3")
     implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.7")
+    // collectAsStateWithLifecycle for the controller-connect StateFlow (v1.8.7, #41).
+    implementation("androidx.lifecycle:lifecycle-runtime-compose:2.8.7")
     implementation("androidx.compose.ui:ui")
     implementation("androidx.compose.ui:ui-graphics")
     implementation("androidx.compose.material3:material3")
@@ -161,4 +172,8 @@ dependencies {
     implementation("net.java.dev.jna:jna:5.15.0@aar")
     // Play Billing — the one-time "Full Unlock" IAP (Workstream M, freemium model).
     implementation("com.android.billingclient:billing-ktx:8.0.0")
+    // Cast Application Framework sender (v1.8.7, #38). Linked but DORMANT: it does
+    // nothing until CastContext is initialized, which only happens behind the
+    // default-off BuildConfig.CHROMECAST_ENABLED flag (see ChromecastSender.kt).
+    implementation("com.google.android.gms:play-services-cast-framework:21.5.0")
 }

android/app/build.gradle.kts

@@ -24,6 +24,17 @@
         android:resizeableActivity="true"
         android:theme="@style/Theme.RustyNES">
 
+        <!-- Cast Application Framework OptionsProvider (v1.8.7, #38). REQUIRED by
+             the SDK to be declared, but only instantiated when CastContext is
+             initialized — and that init is gated behind the default-off
+             BuildConfig.CHROMECAST_ENABLED flag (see ChromecastSender.kt +
+             MainActivity). With the flag off the provider is never touched, so the
+             placeholder Receiver App ID inside it is harmless and the app launches
+             unchanged. The maintainer registers a real App ID before enabling. -->
+        <meta-data
+            android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
+            android:value="com.doublegate.rustynes.RustyNesCastOptionsProvider" />
+
         <!-- Foldable / large-screen support: the activity is resizeable and
              absorbs the fold/unfold + posture config changes itself (so the
              emulation thread + GL surface survive the transition with no