Ship River as a native Android app

[SalvatoreT]

I want to make an Android version of River. I've prototyped it on the salvatoret/android branch, and it runs on a physical device today. Here are the five changes that mattered most.

1. Run a Freenet node on the device

On the web, River is WASM in a browser talking to a remote node. A phone has no browser to host that node, so River now starts a full Network-mode Freenet node in-process when the app launches. Everything else depends on this one.

2. Build the UI as a native Android app, not just WASM

The Dioxus UI now also compiles to a native arm64 binary that renders inside an Android WebView (wry/tao). Browser-only code (web_sys, clipboard, notifications, the browser WebSocket) is gated off the native target so it doesn't crash on startup.

3. Vendor freenet and align the stdlib

Linking freenet as a library meant moving the workspace to freenet-stdlib 0.8 and vendoring freenet with its Windows and macOS GUI dependencies removed, because they clash with dioxus's wry/tao versions. The bundled freenet version also has to track the live network's gateway version, or peers reject the handshake.

4. Connect the UI to the on-device node

The synchronizer talks to the local node over a native WebSocket at 127.0.0.1. Storage lives in the app's private directory, resolved through JNI. A synthetic auth token is registered at startup so the chat delegate accepts the app's own messages.

5. Keep the node alive in the background

A foreground service keeps the node running when the app is backgrounded. It posts an ongoing notification and hands a clean shutdown back to the node's runtime when the user stops it.

---

Still open: a coordinated web republish so Android and existing web users share the same contract namespace. That one is blocked on the web-container signing key.

---

📸 Screenshots

[SalvatoreT]

Hey @sanity, I've started on an Android app. Please let me know if you're interested in landing this here. If not, no worries at all!

[sanity]

Issue Priority Assessment

Generated: 2026-06-09T14:11:07.167825246+00:00
Issue hash: 358d8762

Value Assessment

The codebase is firmly web/WASM-only — no Android-specific code, no wry/tao deps, no native target support. The prototyped Android work lives entirely on Salvatore's fork branch, not in this repo.

Relevance Check: This issue is a feature proposal backed by a working prototype on a separate fork branch (salvatoret/android), not a bug report about something broken in main. The current codebase has no Android-related code whatsoever — the UI crate depends exclusively on wasm-bindgen, web-sys, and dioxus in web mode. The issue is very much still open and unresolved.

User Impact: The impact is potentially significant but currently zero — no Android users exist yet. Android has roughly 70% global mobile market share, and for a decentralized chat app like River, mobile is arguably the primary use case (people don't sit at desktops to chat). If River wants broad adoption beyond the technically sophisticated desktop/browser crowd, a native Android client is a prerequisite. The prototype screenshots show a fully functional messaging experience with an embedded Freenet node running in-process, including 12-peer connectivity, suggesting the core UX gap is closeable. The blocking issue around the web-container signing key (shared contract namespace between Android and web users) represents a real federation problem — Android and web users can't be in the same rooms until that's resolved.

Strategic Alignment: This directly advances River's core goal of decentralized group chat by extending it to where most users actually communicate. The Dioxus ecosystem's cross-platform story (WASM for web, native for desktop/mobile) makes Android a natural target, and the prototype demonstrates it's technically feasible with the existing stack. The "vendor freenet and align stdlib" requirement noted in the issue — where the Android build needs to track the live network's gateway version exactly — creates ongoing maintenance burden and tight coupling with freenet-core releases, which is a meaningful architectural cost. The web-container signing key blocker is also non-trivial and requires coordinated changes to the web publish infrastructure.

Blocking Factor and Urgency: This doesn't block other current work — it's an additive feature. The prototype exists today and runs on physical hardware, which substantially reduces technical risk. The main urgency is competitive: decentralized messaging apps that don't have mobile clients fail to achieve critical mass. The stdlib version coupling issue also means delay increases integration drift. That said, this is high-effort work (vendored freenet, JNI storage, foreground service lifecycle, ongoing stdlib alignment) and the prototype is on a fork — the merge path back to main will require significant review, especially around the freenet-stdlib 0.8 upgrade and vendoring strategy. Overall this is high-value but genuinely large scope, best treated as a tracked roadmap item with clear sub-issues for the signing key blocker and stdlib alignment rather than a single PR.

Cost Assessment

Cost Assessment — Issue #319: Ship River as a Native Android App

The prototype on the salvatoret/android branch demonstrates genuine feasibility, but merging it into main is a large and risky undertaking. The most immediate blocker is a stdlib version gap: main is pinned to freenet-stdlib 0.6.0, while the prototype requires 0.8. That is not a minor bump — it requires auditing all wire-format consumers (riverctl, fdev, the room contract, the delegate) against the new enum layout, running the release smoke-test checklist, and potentially adding migration entries if any WASM changes in the process. The bug-prevention-patterns.md rules call this a Full-tier high-risk surface; any stdlib bump of this magnitude has historically caused production incidents (the v0.2.11 wire-format break, the 2026-04-15 PATH-shadow false alarm).

The scope of the Android-specific code is itself substantial: the Freenet node must run in-process as a library (not as a subprocess), a foreground Android Service must manage its lifecycle, wry/tao must replace web-sys for the WebView, JNI bridges are needed for the app's private storage directory, and a synthetic auth token must be injected at startup. About 25 UI source files already use web_sys or wasm_bindgen directly; every one of those needs a cfg(target_arch = "wasm32") gate or a native alternative. The workspace Cargo graph will also need to carry vendored freenet without its Windows/macOS GUI dependencies, which means keeping a patched vendored copy in sync with upstream — a permanent maintenance burden rather than a one-time cost.

The external/organizational dependency is the real bottleneck. The issue explicitly notes that Android and web users can't share the same contract namespace until the web-container signing key situation is resolved, so the deploy is blocked on a coordination step outside the team's unilateral control. Beyond that, shipping on Android requires a Google Play developer account, app-store review (which can reject or delay for policy reasons), and ongoing maintenance of a native build toolchain (cargo-ndk, Android NDK, signing keys, Play signing infrastructure). These non-code costs — store approval, key management, toolchain maintenance, and the freenet version lock-step — are often what stall mobile initiatives indefinitely.

Risk is high: vendoring freenet means River's network compatibility now depends on manually keeping the vendored copy in sync with whatever version gateways run. Falling behind even one release can cause handshake rejections for all Android users. The foreground service and in-process node introduce concurrency paths the current WASM-only test infrastructure can't exercise, and Android-specific UI behavior (keyboard insets, WebView quirks, back-gesture navigation, notification permissions) requires physical-device or emulator test coverage that CI today has no provision for. Overall, this is a multi-sprint effort with a hard external blocker and a non-trivial ongoing maintenance surface once shipped.

---

Generated by issue-prioritizer