Fix battery voltage null check in RepeaterStatusScreen

Update documentation and dependencies for MeshCore Open
- Replaced sqflite with shared_preferences for local key-value storage in README.md - Updated gradle.properties to include builtInKotlin and newDsl flags - Enhanced translation feature documentation in additional-features.md - Modified BLE protocol documentation to include new command and response codes in ble-protocol.md - Clarified channel management details in channels.md - Improved chat and messaging documentation, including message path viewing and translation options in chat-and-messaging.md - Updated contacts management details in contacts.md - Revised map and location documentation for inferred locations and user interface changes in map-and-location.md - Adjusted navigation flow in navigation.md to reflect changes in screen transitions - Updated notification system details in notifications.md - Enhanced repeater management documentation in repeater-management.md - Clarified scanner and connection process in scanner-and-connection.md - Reorganized settings documentation for better clarity and added new node and location settings in settings.md
2026-06-14 22:55:12 +10:00 · 2026-06-13 02:13:34 -07:00 · 2026-06-13 02:12:00 -07:00 · 2026-06-13 01:58:42 -07:00 · 2026-06-13 00:39:46 -07:00 · 2026-06-13 00:39:13 -07:00
257 changed files with 121617 additions and 18984 deletions
@@ -0,0 +1,38 @@
+name: Deploy to Cloudflare Workers
+
+on:
+  push:
+    tags:
+      - '*'
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          channel: 'stable'
+          # Match local development version which provides Dart 3.11.0
+          flutter-version: '3.41.2'
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Get dependencies
+        run: flutter pub get
+
+      - name: Build Web
+        run: bun run build
+
+      - name: Deploy to Cloudflare
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: deploy
@@ -30,8 +30,12 @@ migrate_working_dir/
 .flutter-plugins-dependencies
 .pub-cache/
 .pub/
+pubspec.lock
 /build/
 /coverage/
+# fvm project files
+.fvm/
+.fvmrc

 # Symbolication related
 app.*.symbols
@@ -57,6 +61,7 @@ secrets.dart
 .DS_Store
 .AppleDouble
 .LSOverride
+macos/Flutter/GeneratedPluginRegistrant.swift

 # iOS
 **/ios/Pods/
@@ -65,6 +70,7 @@ secrets.dart
 **/ios/Flutter/Flutter.podspec

 # Android
+.gradle/
 **/android/.gradle/
 **/android/captures/
 **/android/local.properties
@@ -81,3 +87,10 @@ keystore.properties
 # IDE
 .vscode/launch.json
 .vscode/settings.json
+.contextstream/
+
+# Cloudflare Wrangler
+.wrangler
+
+# Claude Code local working dir (worktrees, jobs, settings)
+.claude/
@@ -0,0 +1 @@
+4.0.0
@@ -0,0 +1 @@
+6.2.4
@@ -6,7 +6,7 @@

 ## BLE Frames & Protocol Notes
 - Nordic UART Service (NUS) UUIDs: Service `6e400001-b5a3-f393-e0a9-e50e24dcca9e`, RX `6e400002-b5a3-f393-e0a9-e50e24dcca9e`, TX `6e400003-b5a3-f393-e0a9-e50e24dcca9e`.
- Discovery: scans for device name prefix `MeshCore-` and filters by `platformName`/`advertisementData.advName`.
+- Discovery: scans for device names matching known prefixes and filters by `platformName`/`advertisementData.advName`.
 - Frames are capped at `maxFrameSize = 172` bytes; byte 0 is the command/response/push code. I/O is `MeshCoreConnector.sendFrame` and `MeshCoreConnector.receivedFrames`.
 - Command codes (to device): `cmdAppStart`=1, `cmdSendTxtMsg`=2, `cmdSendChannelTxtMsg`=3, `cmdGetContacts`=4, `cmdGetDeviceTime`=5, `cmdSetDeviceTime`=6, `cmdSendSelfAdvert`=7, `cmdSetAdvertName`=8, `cmdAddUpdateContact`=9, `cmdSyncNextMessage`=10, `cmdSetRadioParams`=11, `cmdSetRadioTxPower`=12, `cmdResetPath`=13, `cmdSetAdvertLatLon`=14, `cmdRemoveContact`=15, `cmdShareContact`=16, `cmdExportContact`=17, `cmdImportContact`=18, `cmdReboot`=19, `cmdSendLogin`=26, `cmdGetChannel`=31, `cmdSetChannel`=32, `cmdGetRadioSettings`=57.
 - Response codes (from device): `respCodeOk`=0, `respCodeErr`=1, `respCodeContactsStart`=2, `respCodeContact`=3, `respCodeEndOfContacts`=4, `respCodeSelfInfo`=5, `respCodeSent`=6, `respCodeContactMsgRecv`=7, `respCodeChannelMsgRecv`=8, `respCodeCurrTime`=9, `respCodeNoMoreMessages`=10, `respCodeContactMsgRecvV3`=16, `respCodeChannelMsgRecvV3`=17, `respCodeChannelInfo`=18, `respCodeRadioSettings`=25.
@@ -1,6 +1,6 @@
 # MeshCore Open - Flutter Client

-Open-source Flutter client for MeshCore LoRa mesh networking devices.
+Open-source Flutter client for MeshCore LoRa mesh networking devices. Connects to MeshCore-compatible radios over **BLE, TCP, or USB serial** and provides direct/channel chat, contact and channel management, on-map node tracking, repeater administration, and on-device message translation.

 ## Build Commands

@@ -17,6 +17,9 @@ Open-source Flutter client for MeshCore LoRa mesh networking devices.
 # Build iOS
 ~/flutter/bin/flutter build ios

+# Build versioned web release (uses build_pipe)
+~/flutter/bin/dart run build_pipe
+
 # Run static analysis
 ~/flutter/bin/flutter analyze

@@ -28,43 +31,132 @@ Open-source Flutter client for MeshCore LoRa mesh networking devices.

 ```
 lib/
-├── main.dart                    # App entry point, MaterialApp setup with Provider
-├── connector/
-│   └── meshcore_connector.dart  # BLE communication layer (MeshCoreConnector)
-├── screens/
-│   ├── scanner_screen.dart      # BLE device scanning (home screen)
-│   ├── device_screen.dart       # Connected device hub with navigation
-│   ├── chat_screen.dart         # Chat interface (placeholder)
-│   ├── contacts_screen.dart     # Contacts list (placeholder)
-│   └── settings_screen.dart     # Device info and app settings
-└── widgets/
-    └── device_tile.dart         # Device list item with signal strength
+├── main.dart        # Entry point: MultiProvider wiring, locale + theme, initial route
+├── connector/       # Unified BLE/TCP/USB transport layer
+│   ├── meshcore_connector.dart       # Central state holder + ChangeNotifier (all transports)
+│   ├── meshcore_connector_tcp.dart   # TCP transport helper
+│   ├── meshcore_connector_usb.dart   # USB serial transport helper
+│   ├── meshcore_protocol.dart        # Frame size + version constants
+│   └── meshcore_uuids.dart           # Nordic UART UUIDs + scan name prefixes
+├── models/          # Plain data classes (Contact, Channel, Message, Community, …)
+├── services/        # ChangeNotifier services + IO services (retry, translation, ML, …)
+├── storage/         # SharedPreferences-backed stores, scoped per device key
+├── helpers/         # Pure utilities (Smaz compression, GIF parsing, scroll helpers, path hop resolution)
+├── utils/           # Platform / IO / UX utilities (logger, GPX export, dialogs)
+├── theme/           # MeshPalette (defined, not yet wired in main.dart)
+├── l10n/            # ARB localization for 18 locales
+├── icons/           # Custom icon widgets
+├── widgets/         # Reusable widgets (AppBar, BatteryUi, QR, jump-to-bottom, …)
+└── screens/         # ~26 screens — see Screens section below
 ```

+## Screens
+
+All screens are fully implemented (no remaining placeholders).
+
+### Connection / Scanning
+| Screen | Purpose |
+|---|---|
+| `scanner_screen.dart` | BLE device scan and connect — main entry point |
+| `tcp_screen.dart` | Connect to a MeshCore device over TCP/IP |
+| `usb_screen.dart` | Connect to a MeshCore device over USB serial |
+| `discovery_screen.dart` | Browse all discovered (non-contact) mesh nodes |
+| `chrome_required_screen.dart` | Web gate for non-Chrome browsers (BLE unavailable) |
+
+### Chat / Messaging
+| Screen | Purpose |
+|---|---|
+| `chat_screen.dart` | Direct (private) messaging with a contact |
+| `channel_chat_screen.dart` | Group messaging inside a named channel |
+| `channels_screen.dart` | List and manage channels (add/edit/delete) |
+| `channel_message_path_screen.dart` | Hop-by-hop route a channel message took, with map overlay |
+
+### Contacts / Neighbors
+| Screen | Purpose |
+|---|---|
+| `contacts_screen.dart` | Full contacts list with previews and management |
+| `neighbors_screen.dart` | Nodes directly heard by the connected radio (one-hop) |
+
+### Repeater Management
+| Screen | Purpose |
+|---|---|
+| `repeater_hub_screen.dart` | Top-level repeater hub; navigates to sub-screens |
+| `repeater_status_screen.dart` | Live status of a managed repeater node |
+| `repeater_cli_screen.dart` | Raw command-line interface to a repeater |
+| `repeater_settings_screen.dart` | Full radio/node settings editor for a repeater |
+
+### Map / Location
+| Screen | Purpose |
+|---|---|
+| `map_screen.dart` | Main map view of contacts/nodes with live GPS positions |
+| `line_of_sight_map_screen.dart` | Terrain LOS analysis between configurable endpoints |
+| `path_trace_map.dart` | Animates the hop path a direct message traveled |
+| `map_cache_screen.dart` | Download/clear offline map tile cache |
+| `community_qr_scanner_screen.dart` | Scan QR to join a mesh community/channel |
+
+### Settings / Debug / Diagnostics
+| Screen | Purpose |
+|---|---|
+| `settings_screen.dart` | Connected device settings: radio params, identity, GPS |
+| `app_settings_screen.dart` | App preferences: theme, units, map source, notifications |
+| `app_debug_log_screen.dart` | In-app log viewer (app-layer messages) |
+| `ble_debug_log_screen.dart` | In-app log viewer (raw BLE frame traffic) |
+| `companion_radio_stats_screen.dart` | RF stats (RSSI, SNR, packet counts) for paired radio |
+| `telemetry_screen.dart` | Battery / sensor / environmental telemetry for a contact |
+
 ## Architecture

 ### State Management
- **Provider** with `ChangeNotifier` pattern
- `MeshCoreConnector` is the central state holder for BLE connection
- Screens use `Consumer<MeshCoreConnector>` for reactive UI updates
+
+`Provider` with `ChangeNotifier`. `main.dart` wires a `MultiProvider` with the following:
+
+| Provider | Role |
+|---|---|
+| `MeshCoreConnector` | Active transport (BLE/TCP/USB), connection state, frame I/O |
+| `MessageRetryService` | ACK tracking and retry scheduling with backoff |
+| `PathHistoryService` | Per-contact routing history (LRU cache, 50 contacts) |
+| `AppSettingsService` | App preferences (theme, units, locale, notifications) |
+| `BleDebugLogService` | Raw BLE frame log buffer |
+| `AppDebugLogService` | Structured app log buffer |
+| `ChatTextScaleService` | Pinch-to-zoom text scale for chat screens |
+| `TranslationService` | On-device LLM translation (llamadart) |
+| `UiViewStateService` | Contacts/channels sort/filter/search state |
+| `TimeoutPredictionService` | ML linear regression for ACK timeout prediction |
+| `StorageService` | Path history + delivery observation persistence |
+| `MapTileCacheService` | OSM tile pre-cache |
+
+Screens consume these via `Consumer<T>` (or `context.watch<T>()` / `context.read<T>()`) for reactive UI.
+
+### Storage / Persistence
+
+All stores in `lib/storage/` use `PrefsManager` (a `SharedPreferences` singleton initialized in `main()`). Most stores **scope keys by the first 10 hex chars of the connected device's public key**, so per-radio data is isolated.
+
+| Store | Persists |
+|---|---|
+| `message_store`, `channel_message_store` | Direct + channel messages |
+| `contact_store`, `contact_discovery_store` | Known + discovered contacts |
+| `channel_store`, `channel_order_store`, `channel_settings_store` | Channels, display order, per-channel Smaz toggle |
+| `community_store` | Communities (32-byte shared secrets) |
+| `contact_group_store`, `contact_settings_store` | Groups, per-contact Smaz toggle |
+| `unread_store` | Per-contact unread counts (debounced writes) |
+
+GGUF translation models are stored as files (not SharedPreferences) via `translation_file_store`.

 ### Theming
 - Material 3 design (`useMaterial3: true`)
 - System-based dark/light mode (`ThemeMode.system`)
 - Blue color scheme seed
+- `lib/theme/mesh_theme.dart` defines a warm-dark `MeshPalette` (phosphor-green accents) but is **not currently wired** in `main.dart` — available for a future redesign

-## BLE Protocol
+### Localization

-### Nordic UART Service (NUS)
- **Service UUID**: `6e400001-b5a3-f393-e0a9-e50e24dcca9e`
- **RX Characteristic**: `6e400002-b5a3-f393-e0a9-e50e24dcca9e` (Write to device)
- **TX Characteristic**: `6e400003-b5a3-f393-e0a9-e50e24dcca9e` (Notify from device)
+18 locales supported via Flutter's standard ARB pipeline (`lib/l10n/`): en, de, es, fr, it, pt, ru, uk, bg, hu, ja, ko, nl, pl, sk, sl, sv, zh. Language override comes from `AppSettingsService.settings.languageOverride`. Use the `context.l10n` extension (`lib/l10n/l10n.dart`) for translated strings; contact-type names live in `contact_localization.dart`.

-### Device Discovery
- Scans for devices with name prefix `MeshCore-`
- Filters by `platformName` or `advertisementData.advName`
+## Transports

-### Connection States
+`MeshCoreConnector` unifies all three transports under one `ChangeNotifier`. There is **no shared base class** — selection is via the `MeshCoreTransportType { bluetooth, usb, tcp }` enum, and BLE/TCP/USB share the same connection-state enum, send/receive API, and frame protocol.
+
+### Connection State
 ```dart
 enum MeshCoreConnectionState {
  disconnected,
@@ -75,28 +167,137 @@ enum MeshCoreConnectionState {
 }
 ```

-### Frame I/O
- **Send**: `MeshCoreConnector.sendFrame(Uint8List data)`
- **Receive**: `MeshCoreConnector.receivedFrames` stream of `Uint8List`
+### Frame I/O (all transports)
+- **Send**: `MeshCoreConnector.sendFrame(Uint8List data, {String? channelSendQueueId, bool expectsGenericAck})`
+- **Receive**: `Stream<Uint8List> get receivedFrames`
+- **Protocol constants** (`meshcore_protocol.dart`): `maxFrameSize = 172`, `maxTextPayloadBytes = 160`, `appProtocolVersion = 4`
+
+### BLE — Nordic UART Service (NUS)
+- **Service UUID**: `6e400001-b5a3-f393-e0a9-e50e24dcca9e`
+- **RX Characteristic** (write to device): `6e400002-b5a3-f393-e0a9-e50e24dcca9e`
+- **TX Characteristic** (notify from device): `6e400003-b5a3-f393-e0a9-e50e24dcca9e`
+- **Discovery**: scans for devices whose name starts with `MeshCore-`, `Whisper-`, `WisCore-`, `Seeed`, `Lilygo`, `HT-`, or `LowMesh_MC_` (filters on both `platformName` and `advertisementData.advName`)
+- **Linux**: `linux_ble_pairing_service.dart` falls back to `bluetoothctl` when BlueZ agent prompts fail
+
+### TCP
+- Manual host/port entry, persisted via `AppSettingsService` (`tcpServerAddress`, `tcpServerPort`)
+- UI hint: `192.168.40.10` / port `5000`
+- Disabled on web (`PlatformInfo.isWeb`)
+- API: `MeshCoreConnector.connectTcp(host: ..., port: ...)`
+
+### USB Serial (flserial)
+- Default baud rate: `115200`
+- Port enumeration: `MeshCoreConnector.listUsbPorts()`
+- COBS-framed packets via `usb_serial_frame_codec.dart`
+- macOS device-name resolution via `ioreg` (`utils/macos_usb_device_names.dart`)
+- API: `MeshCoreConnector.connectUsb(portName: ..., baudRate: 115200)`

 ## Dependencies

+App version: `9.5.0+13` — Dart SDK constraint: `^3.9.2`
+
+**Connectivity**
+
 | Package | Version | Purpose |
 |---------|---------|---------|
-| flutter_blue_plus | ^2.1.0 | BLE communication |
-| provider | ^6.1.5+1 | State management |
-| cupertino_icons | ^1.0.8 | iOS-style icons |
+| flutter_blue_plus | ^2.1.0 | BLE scanning, connecting, and UART data transfer |
+| flutter_blue_plus_platform_interface | ^9.0.2 | Platform-interface layer required by flutter_blue_plus |
+| flserial | git (MeshEnvy fork) | USB serial transport for wired device connections (TODO: upstream pending) |
+
+**State / Storage**
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| provider | ^6.1.5+1 | ChangeNotifier-based state management across screens |
+| shared_preferences | ^2.2.2 | Persistent key-value storage for user settings |
+| path_provider | ^2.1.5 | Locates platform-appropriate directories for file I/O |
+
+**Crypto**
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| crypto | ^3.0.3 | SHA/HMAC hashing used in message authentication |
+| pointycastle | ^4.0.0 | AES encryption/decryption for channel and direct messages |
+| uuid | ^4.3.3 | Generates UUIDs for message and contact identity |
+
+**Maps & Location**
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| flutter_map | ^8.2.2 | Interactive tile map for node positions and path traces |
+| latlong2 | ^0.9.1 | LatLng coordinate type used throughout map and GPS code |
+| gpx | ^2.3.0 | Export node paths as GPX track files |
+
+**UI**
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| material_symbols_icons | ^4.2928.1 | Extended Material Symbols icon set (line-of-sight, etc.) |
+| flutter_svg | ^2.0.10+1 | Renders SVG assets (custom icons such as LoS indicator) |
+| cached_network_image | ^3.4.1 | Caches map tile images downloaded over the network |
+| flutter_cache_manager | ^3.4.1 | Underlying cache manager used by cached_network_image |
+| flutter_linkify | ^6.0.0 | Auto-detects and makes URLs tappable in chat messages |
+| mobile_scanner | ^7.1.4 | QR/barcode scanning for contact and channel import |
+| qr_flutter | ^4.1.0 | Generates QR codes for sharing contacts and channels |
+| cupertino_icons | ^1.0.8 | iOS-style icon font (bundled for completeness) |
+| characters | ^1.4.0 | Unicode-aware string operations for message text handling |
+
+**Notifications / Background**
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| flutter_local_notifications | ^22.0.0 | Shows local push notifications for incoming messages |
+| flutter_foreground_task | ^9.2.0 | Keeps the app alive in background to maintain BLE/USB connection |
+
+**ML / AI**
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| ml_algo | ^16.0.0 | OLS regression used in `timeout_prediction_service.dart` to predict message ACK timeouts |
+| ml_dataframe | ^1.0.0 | DataFrame input format required by ml_algo |
+| llamadart | ^0.8.0 | On-device LLM inference used in `translation_service.dart` for message translation |
+| flutter_langdetect | ^0.0.1 | Detects a message's source language in `translation_service.dart` before translating |
+
+**Misc**
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| http | ^1.2.0 | Fetches tile URLs and any remote API calls |
+| url_launcher | ^6.3.0 | Opens URLs in the system browser from linkified chat text |
+| share_plus | ^13.1.0 | Shares files (e.g. exported GPX tracks) via the system share sheet |
+| package_info_plus | ^10.1.0 | Reads app version/build number displayed in settings |
+| web | ^1.1.1 | Web-platform APIs for USB serial and browser detection on Flutter Web |
+| intl | any | Internationalization and locale formatting (required by flutter_localizations) |
+| build_pipe | ^0.3.1 | CI/CD build pipeline configuration (web release builds with versioned assets) |

 ## Platform Configuration

 ### Android (`android/app/src/main/AndroidManifest.xml`)
- `BLUETOOTH`, `BLUETOOTH_ADMIN` (API 30 and below)
- `BLUETOOTH_SCAN`, `BLUETOOTH_CONNECT`, `BLUETOOTH_ADVERTISE` (API 31+)
- `ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION` (for BLE scanning)
+- `INTERNET` (map tiles, translation model downloads)
+- `BLUETOOTH`, `BLUETOOTH_ADMIN` (API ≤ 30)
+- `BLUETOOTH_SCAN` (with `neverForLocation`), `BLUETOOTH_CONNECT`, `BLUETOOTH_ADVERTISE` (API 31+)
+- `ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION` (BLE scanning on API ≤ 30)
+- `POST_NOTIFICATIONS` (API 33+)
+- `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_CONNECTED_DEVICE` (background BLE/USB connection)
+- `WAKE_LOCK`
+- `CAMERA` (QR scanning, declared as optional feature)
+- USB host hardware feature (optional)
+
+`flutter_foreground_task` registers a `ForegroundService` with `foregroundServiceType="connectedDevice"` and `stopWithTask="false"`.
+
+**Build config (`android/app/build.gradle.kts`)**: `applicationId = com.meshcore.meshcore_open`, NDK `29.0.14206865`, Java 8 core-library desugaring (`desugar_jdk_libs:2.1.4`), release signing via `key.properties` (debug fallback).

 ### iOS (`ios/Runner/Info.plist`)
- `NSBluetoothAlwaysUsageDescription`
- `NSBluetoothPeripheralUsageDescription`
+- `NSBluetoothAlwaysUsageDescription`, `NSBluetoothPeripheralUsageDescription`
+- `NSCameraUsageDescription` (QR scanning to join communities)
+- Background modes: `bluetooth-central`
+- `LSApplicationQueriesSchemes`: `http`, `https`
+
+### Web (`web/`)
+PWA scaffold present but boilerplate (`manifest.json` and `index.html` are unmodified Flutter defaults). BLE is unsupported in browsers; TCP and Web Serial USB may work in Chrome only. `ChromeRequiredScreen` gates non-Chrome web users. Versioned releases are produced via `build_pipe` (`?v=<pubspec version>` cache busting, no service worker).
+
+### Desktop
+`linux/`, `windows/`, and `macos/` directories are present as Flutter scaffolds. No app-specific native config has been added; BLE on desktop has not been validated.

 ## Coding Conventions

@@ -123,14 +324,14 @@ enum MeshCoreConnectionState {

 | File | Purpose |
 |------|---------|
-| `lib/connector/meshcore_connector.dart` | All BLE logic - scanning, connecting, data transfer |
-| `lib/screens/scanner_screen.dart` | Entry point UI, device list |
-| `lib/main.dart` | App configuration, theme, Provider setup |
-| `pubspec.yaml` | Dependencies and project metadata |
-
-## Placeholder Screens
-
-The following screens are implemented as placeholders and need full implementation:
- `chat_screen.dart` - Mesh chat functionality
- `contacts_screen.dart` - Contact management
- `settings_screen.dart` - Radio settings, node identity, location (partially implemented)
+| `lib/main.dart` | App configuration, MultiProvider setup, theme, locale, initial route |
+| `lib/connector/meshcore_connector.dart` | Unified BLE/TCP/USB transport state holder |
+| `lib/connector/meshcore_protocol.dart` | Frame size limits and protocol version |
+| `lib/connector/meshcore_uuids.dart` | NUS UUIDs and BLE scan name prefixes |
+| `lib/services/app_settings_service.dart` | App-wide settings (`AppSettings` JSON in SharedPreferences) |
+| `lib/services/storage_service.dart` | Path history + delivery observation persistence |
+| `lib/services/message_retry_service.dart` | ACK tracking + retry scheduling |
+| `lib/services/translation_service.dart` | On-device LLM translation (llamadart) |
+| `lib/storage/prefs_manager.dart` | SharedPreferences singleton initialized in `main()` |
+| `lib/screens/scanner_screen.dart` | Home screen — BLE scan and connect |
+| `pubspec.yaml` | Dependencies and project metadata (current version `9.5.0+13`) |
@@ -0,0 +1,71 @@
+# How to contribute to Meshcore Open
+
+Before submitting any pull requests (PR), please review the following information.
+
+Unsolicited PRs without previous discussion or open issues may be
+rejected. As may changes that are too broad (i.e. 100 files changed) or that
+cover too many separate changes. If the changes are clearly AI generated they
+may also be rejected. [See more](#ai-use)
+
+## First Step Checklist
+
+### **Did you find a bug?**
+
+* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/zjs81/meshcore-open/issues).
+
+* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/zjs81/meshcore-open/issues/new).
+Be sure to include a **title and clear description**, as much relevant
+information as possible, and a **code sample** or an **executable test case**
+demonstrating the expected behavior that is not occurring. You can also include
+screenshots or video.
+
+* DO NOT start work and submit a PR at this time, please discuss the issue and
+your implementation plan first.
+
+### **Did you fix whitespace, format code, or make a purely cosmetic patch?**
+
+Changes that are cosmetic in nature and do not add anything substantial to the
+stability, functionality, or testability of the application will generally not
+be accepted.
+
+### **Do you intend to add a new feature or change an existing one?**
+
+* Suggest your change in a new issue as a feature request.
+
+* DO NOT start work and submit a PR at this time, please discuss the change and
+your implementation plan first.
+
+* After it is generally decided that the feature or change fits the goals of the
+project you can start work or open a PR if you have already started.
+
+## Submitting your patch
+
+* All changes should be based on the `dev` branch. When creating your PR please
+be sure to change the target to merge into dev, and when starting work on a new
+branch be sure to start on latest `dev`.
+
+* Ensure the PR description clearly describes the problem and solution. Include
+the relevant issue number if applicable.
+
+* The PR should contain **one commit** only, the commit message should have a
+clear title followed by a new line and then brief description if needed. PR with
+multiple commits will be squashed into one before merging if required. See
+[Git Mastery](https://git-mastery.org/lessons/commitMessage/) for more
+information on good commit messages.
+
+* **Before committing changes** on your branch, be sure to run both
+`dart format .` and `flutter analyze`. The continuous development checks will
+fail if issues here are not addressed before hand.
+
+## AI-use
+
+Everyone loves some help, AI agents are a tool in many of our belts. The project
+is not anti-AI.
+
+There are some limits to acceptable use however. Generally:
+
+* All code generated by AI should be thoroughly reviewed by the contributor.
+* The changes should be tightly controlled to not change anything out of scope
+for the patch, bug fix, etc.
+* The contributor should have a good understanding of what the code does and how
+the application works in order to effectively be able to manage the agent.
@@ -6,6 +6,8 @@ Open-source Flutter client for MeshCore LoRa mesh networking devices.

 MeshCore Open is a cross-platform mobile application for communicating with MeshCore LoRa mesh network devices via Bluetooth Low Energy (BLE). The app enables long-range, off-grid communication through peer-to-peer messaging, public channels, and mesh networking capabilities.

+**Website:** [meshcoreopen.org](https://meshcoreopen.org/)
+
 <a href="http://apps.obtainium.imranr.dev/redirect.html?r=obtainium://add/https://github.com/zjs81/meshcore-open">
        <img src="assets/badges/badge_obtainium.png" height="80" align="center" alt="Get it on Obtainium"/>
 </a>
@@ -51,7 +53,7 @@ MeshCore Open is a cross-platform mobile application for communicating with Mesh

 ### Device Management

- **BLE Connection**: Scan and connect to MeshCore devices via Bluetooth
+- **BLE, USB, TCP Connection**: Scan and connect to MeshCore devices via Bluetooth, USB or TCP
 - **Device Settings**: Configure radio parameters, power settings, and network options
 - **Battery Monitoring**: Real-time battery status with chemistry-specific voltage curves
 - **Firmware Updates**: Over-the-air firmware updates via BLE (coming soon)
@@ -75,9 +77,16 @@ MeshCore Open is a cross-platform mobile application for communicating with Mesh

 ### Platform Support

- ✅ **Android**: Full support (API 21+)
- ✅ **iOS**: Full support (iOS 12+)
- 🚧 **Desktop**: Limited support (macOS/Linux/Windows)
+| Feature            | Android (API 21+) | iOS (12+) | Linux | Windows | macOS |                Web                |
+|--------------------|:-----------------:|:---------:|:-----:|:-------:|:-----:|:---------------------------------:|
+| BLE companion      | ✅                | ✅        | ✅   | ✅      | ✅    | ✅                                |
+| USB companion      | ✅                | 🚧        | ✅   | ✅      | ✅    | ✅                                |
+| TCP companion      | ✅                | 🚧        | ✅   | ✅      | ✅    | ❌<br>(requires websocket bridge) |
+| Core Functionality | ✅                | ✅        | ✅   | ✅      | ✅    | ✅                                |
+| Mesh Network       | ✅                | ✅        | ✅   | ✅      | ✅    | ✅                                |
+| Map & Location     | ✅                | ✅        | ✅   | ✅      | ✅    | ✅                                |
+| Device Management  | ✅                | ✅        | ✅   | ✅      | ✅    | ✅                                |
+| Repeater Hub       | ✅                | ✅        | ✅   | ✅      | ✅    | ✅                                |

 ### Dependencies

@@ -85,12 +94,12 @@ MeshCore Open is a cross-platform mobile application for communicating with Mesh
 |---------|---------|
 | flutter_blue_plus | Bluetooth Low Energy communication |
 | provider | State management |
-| sqflite | Local database storage |
+| shared_preferences | Local key-value storage (scoped per device) |
 | flutter_map | Interactive map display |
 | latlong2 | Geographic coordinate handling |
 | flutter_local_notifications | Background notification support |
-| smaz | Message compression |
 | pointycastle | Cryptographic operations |
+| llamadart | On-device LLM message translation |
 | intl | Internationalization and date formatting |

 ## Getting Started
@@ -143,7 +152,8 @@ lib/
 ├── main.dart                    # App entry point
 ├── connector/
 │   ├── meshcore_connector.dart  # BLE communication & state management
-│   └── meshcore_protocol.dart   # Protocol definitions & frame parsing
+│   ├── meshcore_protocol.dart   # Protocol definitions & frame parsing
+│   └── meshcore_uuids.dart      # Device names and IDs (add prefixes here!)
 ├── screens/
 │   ├── scanner_screen.dart      # Device scanning (home screen)
 │   ├── contacts_screen.dart     # Contact list
@@ -177,7 +187,16 @@ lib/

 ### Device Discovery

-Devices are discovered by scanning for BLE advertisements with the name prefix `MeshCore-`
+Devices are discovered by scanning for BLE advertisements with known MeshCore device name prefixes. These are currently:
+    - `MeshCore-`
+    - `Whisper-`
+    - `WisCore-`
+    - `HT-`
+    - `LowMesh_MC_`
+    - `NRF52`
+
+New device prefixes can be added in `lib/connector/meshcore_uuids.dart`.
+

 ### Message Format

@@ -188,6 +207,7 @@ Messages are transmitted as binary frames using a custom protocol optimized for
 ### App Settings

 - **Theme**: System default, light, or dark mode
+- **Language**: Use one of 15 languages (English, Chinese, French, Spanish, Portuguese, German, Dutch, Polish, Swedish, Italian, Slovak, Slovene, Bulgarian, Russian, Ukrainian)
 - **Notifications**: Configurable for messages, channels, and node advertisements
 - **Battery Chemistry**: Support for NMC, LiFePO4, and LiPo battery types
 - **Message Retry**: Automatic retry with configurable path clearing
@@ -230,6 +250,11 @@ If you find MeshCore Open useful and would like to support development, you can

 **Solana Address:** `F15YanjZj96YTBtKJYgNa8RLQLCZkx5CEwogPWkqXeoQ`

+
+**Monero Address:** `453TxnpUqjkJtXxzdjMsrgERNkBRXEGamPbpC45ENrvKAk9tH7kZbxWF82Hz66etgDZyXFPEBU2JUEqhLeJyWt9kBvTVy5m`
+
+**Bitcoin Address:** `bc1qh45x28v8dslcg4v4upmqd9g0mvc3lnyffmyzr5`
+
 Your support helps maintain and improve this open-source project!

 ## Acknowledgments
@@ -16,16 +16,16 @@ if (keystorePropertiesFile.exists()) {
 android {
    namespace = "com.meshcore.meshcore_open"
    compileSdk = flutter.compileSdkVersion
-    ndkVersion = flutter.ndkVersion
+    ndkVersion = "29.0.14206865"

    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_11
-        targetCompatibility = JavaVersion.VERSION_11
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
        isCoreLibraryDesugaringEnabled = true
    }

    kotlinOptions {
-        jvmTarget = JavaVersion.VERSION_11.toString()
+        jvmTarget = JavaVersion.VERSION_17.toString()
    }

    defaultConfig {
@@ -83,5 +83,5 @@ flutter {
 }

 dependencies {
-    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.4")
+    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
 }
@@ -19,6 +19,7 @@
    <!-- Camera permission for QR code scanning -->
    <uses-permission android:name="android.permission.CAMERA"/>
    <uses-feature android:name="android.hardware.camera" android:required="false"/>
+    <uses-feature android:name="android.hardware.usb.host" android:required="false"/>

    <application
        android:label="meshcore_open"
@@ -1,5 +1,18 @@
 package com.meshcore.meshcore_open

 import io.flutter.embedding.android.FlutterActivity
+import io.flutter.embedding.engine.FlutterEngine

-class MainActivity : FlutterActivity()
+class MainActivity : FlutterActivity() {
+    private val usbFunctions by lazy { MeshcoreUsbFunctions(this) }
+
+    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
+        super.configureFlutterEngine(flutterEngine)
+        usbFunctions.configureFlutterEngine(flutterEngine)
+    }
+
+    override fun onDestroy() {
+        usbFunctions.dispose()
+        super.onDestroy()
+    }
+}
@@ -0,0 +1,582 @@
+package com.meshcore.meshcore_open
+
+import android.app.PendingIntent
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.hardware.usb.UsbConstants
+import android.hardware.usb.UsbDevice
+import android.hardware.usb.UsbDeviceConnection
+import android.hardware.usb.UsbEndpoint
+import android.hardware.usb.UsbInterface
+import android.hardware.usb.UsbManager
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import io.flutter.embedding.android.FlutterActivity
+import io.flutter.embedding.engine.FlutterEngine
+import io.flutter.plugin.common.EventChannel
+import io.flutter.plugin.common.MethodCall
+import io.flutter.plugin.common.MethodChannel
+import java.util.Locale
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+
+class MeshcoreUsbFunctions(
+    private val activity: FlutterActivity,
+) {
+    private companion object {
+        const val usbRecipientInterface = 0x01
+    }
+
+    private val usbMethodChannelName = "meshcore_open/android_usb_serial"
+    private val usbEventChannelName = "meshcore_open/android_usb_serial_events"
+    private val usbPermissionAction = "com.meshcore.meshcore_open.USB_PERMISSION"
+
+    private val usbManager by lazy {
+        activity.getSystemService(Context.USB_SERVICE) as UsbManager
+    }
+    private val mainHandler = Handler(Looper.getMainLooper())
+    private val usbIoExecutor: ExecutorService = Executors.newSingleThreadExecutor()
+
+    @Volatile private var eventSink: EventChannel.EventSink? = null
+    @Volatile private var usbConnection: UsbDeviceConnection? = null
+    @Volatile private var usbInEndpoint: UsbEndpoint? = null
+    @Volatile private var usbOutEndpoint: UsbEndpoint? = null
+    @Volatile private var controlInterface: UsbInterface? = null
+    @Volatile private var dataInterface: UsbInterface? = null
+    private var readThread: Thread? = null
+    @Volatile private var isReading = false
+    @Volatile private var connectedDeviceName: String? = null
+
+    private var pendingConnectResult: MethodChannel.Result? = null
+    private var pendingConnectPortName: String? = null
+    private var pendingConnectBaudRate: Int = 115200
+
+    private data class PortConfig(
+        val controlInterface: UsbInterface?,
+        val dataInterface: UsbInterface,
+        val inEndpoint: UsbEndpoint,
+        val outEndpoint: UsbEndpoint,
+    )
+
+    private val permissionReceiver =
+        object : BroadcastReceiver() {
+            override fun onReceive(context: Context?, intent: Intent?) {
+                when (intent?.action) {
+                    UsbManager.ACTION_USB_DEVICE_DETACHED -> {
+                        handleUsbDetached(intent)
+                        return
+                    }
+                    usbPermissionAction -> Unit
+                    else -> return
+                }
+
+                val result = pendingConnectResult
+                val portName = pendingConnectPortName
+                pendingConnectResult = null
+                pendingConnectPortName = null
+
+                if (result == null || portName == null) {
+                    return
+                }
+
+                val device = findUsbDevice(portName)
+                if (device == null) {
+                    result.error(
+                        "usb_device_missing",
+                        null,
+                        null,
+                    )
+                    return
+                }
+
+                val granted =
+                    intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)
+                if (!granted || !usbManager.hasPermission(device)) {
+                    result.error("usb_permission_denied", null, null)
+                    return
+                }
+
+                openUsbDevice(device, pendingConnectBaudRate, result)
+            }
+        }
+
+    fun configureFlutterEngine(flutterEngine: FlutterEngine) {
+        registerUsbPermissionReceiver()
+
+        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, usbMethodChannelName)
+            .setMethodCallHandler { call, result ->
+                when (call.method) {
+                    "listPorts" -> result.success(listUsbPorts())
+                    "connect" -> handleUsbConnect(call, result)
+                    "write" -> handleUsbWrite(call, result)
+                    "disconnect" -> {
+                        scheduleCloseUsbConnection {
+                            result.success(null)
+                        }
+                    }
+                    else -> result.notImplemented()
+                }
+            }
+
+        EventChannel(flutterEngine.dartExecutor.binaryMessenger, usbEventChannelName)
+            .setStreamHandler(
+                object : EventChannel.StreamHandler {
+                    override fun onListen(arguments: Any?, events: EventChannel.EventSink) {
+                        eventSink = events
+                    }
+
+                    override fun onCancel(arguments: Any?) {
+                        eventSink = null
+                    }
+                },
+            )
+    }
+
+    fun dispose() {
+        closeUsbConnection()
+        usbIoExecutor.shutdownNow()
+        try {
+            activity.unregisterReceiver(permissionReceiver)
+        } catch (_: IllegalArgumentException) {
+        }
+    }
+
+    private fun registerUsbPermissionReceiver() {
+        val filter =
+            IntentFilter().apply {
+                addAction(usbPermissionAction)
+                addAction(UsbManager.ACTION_USB_DEVICE_DETACHED)
+            }
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            activity.registerReceiver(permissionReceiver, filter, Context.RECEIVER_NOT_EXPORTED)
+        } else {
+            @Suppress("DEPRECATION")
+            activity.registerReceiver(permissionReceiver, filter)
+        }
+    }
+
+    private fun listUsbPorts(): List<String> {
+        return usbManager.deviceList.values.map { device ->
+            val productName = device.productName ?: "USB Serial Device"
+            val vendorProduct =
+                String.format(
+                    Locale.US,
+                    "VID:%04X PID:%04X",
+                    device.vendorId,
+                    device.productId,
+                )
+            "${device.deviceName} - $productName - $vendorProduct"
+        }
+    }
+
+    private fun handleUsbConnect(call: MethodCall, result: MethodChannel.Result) {
+        val portName = call.argument<String>("portName")
+        val baudRate = call.argument<Int>("baudRate") ?: 115200
+        if (portName.isNullOrBlank()) {
+            result.error("usb_invalid_port", null, null)
+            return
+        }
+
+        val device = findUsbDevice(portName)
+        if (device == null) {
+            result.error("usb_device_missing", null, null)
+            return
+        }
+
+        if (usbManager.hasPermission(device)) {
+            openUsbDevice(device, baudRate, result)
+            return
+        }
+
+        if (pendingConnectResult != null) {
+            result.error("usb_busy", null, null)
+            return
+        }
+
+        pendingConnectResult = result
+        pendingConnectPortName = portName
+        pendingConnectBaudRate = baudRate
+
+        val permissionIntent = PendingIntent.getBroadcast(
+            activity,
+            0,
+            Intent(usbPermissionAction).setPackage(activity.packageName),
+            pendingIntentFlags(),
+        )
+        usbManager.requestPermission(device, permissionIntent)
+    }
+
+    private fun handleUsbWrite(call: MethodCall, result: MethodChannel.Result) {
+        val data = call.argument<ByteArray>("data")
+        val connection = usbConnection
+        val endpoint = usbOutEndpoint
+        if (data == null) {
+            result.error("usb_invalid_data", null, null)
+            return
+        }
+        if (connection == null || endpoint == null) {
+            result.error("usb_not_connected", null, null)
+            return
+        }
+
+        usbIoExecutor.execute {
+            try {
+                writeToDevice(data)
+                mainHandler.post { result.success(null) }
+            } catch (error: Exception) {
+                mainHandler.post {
+                    result.error("usb_write_failed", error.message, null)
+                }
+            }
+        }
+    }
+
+    private fun findUsbDevice(portName: String): UsbDevice? {
+        val devices = usbManager.deviceList.values
+        val exactMatch = devices.firstOrNull { it.deviceName == portName }
+        if (exactMatch != null) {
+            return exactMatch
+        }
+
+        val normalizedName = portName.substringBefore(" - ").trim()
+        return devices.firstOrNull { it.deviceName == normalizedName }
+    }
+
+    private fun openUsbDevice(
+        device: UsbDevice,
+        baudRate: Int,
+        result: MethodChannel.Result,
+    ) {
+        usbIoExecutor.execute {
+            try {
+                closeUsbConnection()
+
+                val config = resolvePortConfig(device)
+                if (config == null) {
+                    mainHandler.post {
+                        result.error(
+                            "usb_driver_missing",
+                            null,
+                            null,
+                        )
+                    }
+                    return@execute
+                }
+
+                val connection = usbManager.openDevice(device)
+                if (connection == null) {
+                    mainHandler.post {
+                        result.error(
+                            "usb_open_failed",
+                            null,
+                            null,
+                        )
+                    }
+                    return@execute
+                }
+
+                if (!connection.claimInterface(config.dataInterface, true)) {
+                    connection.close()
+                    mainHandler.post {
+                        result.error(
+                            "usb_open_failed",
+                            null,
+                            null,
+                        )
+                    }
+                    return@execute
+                }
+
+                if (config.controlInterface != null &&
+                    config.controlInterface.id != config.dataInterface.id &&
+                    !connection.claimInterface(config.controlInterface, true)
+                ) {
+                    connection.releaseInterface(config.dataInterface)
+                    connection.close()
+                    mainHandler.post {
+                        result.error(
+                            "usb_open_failed",
+                            null,
+                            null,
+                        )
+                    }
+                    return@execute
+                }
+
+                usbConnection = connection
+                usbInEndpoint = config.inEndpoint
+                usbOutEndpoint = config.outEndpoint
+                controlInterface = config.controlInterface
+                dataInterface = config.dataInterface
+
+                configureDevice(connection, config, baudRate)
+
+                connectedDeviceName = device.deviceName
+                startReadLoop()
+
+                mainHandler.post {
+                    result.success(null)
+                }
+            } catch (error: Exception) {
+                closeUsbConnection()
+                mainHandler.post {
+                    result.error("usb_connect_failed", error.message, null)
+                }
+            }
+        }
+    }
+
+    private fun resolvePortConfig(device: UsbDevice): PortConfig? {
+        var preferredDataInterface: UsbInterface? = null
+        var preferredInEndpoint: UsbEndpoint? = null
+        var preferredOutEndpoint: UsbEndpoint? = null
+        var fallbackDataInterface: UsbInterface? = null
+        var fallbackInEndpoint: UsbEndpoint? = null
+        var fallbackOutEndpoint: UsbEndpoint? = null
+        var preferredControlInterface: UsbInterface? = null
+
+        for (interfaceIndex in 0 until device.interfaceCount) {
+            val usbInterface = device.getInterface(interfaceIndex)
+            var inEndpoint: UsbEndpoint? = null
+            var outEndpoint: UsbEndpoint? = null
+
+            for (endpointIndex in 0 until usbInterface.endpointCount) {
+                val endpoint = usbInterface.getEndpoint(endpointIndex)
+                if (endpoint.type != UsbConstants.USB_ENDPOINT_XFER_BULK) {
+                    continue
+                }
+                when (endpoint.direction) {
+                    UsbConstants.USB_DIR_IN -> if (inEndpoint == null) inEndpoint = endpoint
+                    UsbConstants.USB_DIR_OUT -> if (outEndpoint == null) outEndpoint = endpoint
+                }
+            }
+
+            val hasDataPair = inEndpoint != null && outEndpoint != null
+            when {
+                usbInterface.interfaceClass == UsbConstants.USB_CLASS_COMM &&
+                    preferredControlInterface == null -> {
+                    preferredControlInterface = usbInterface
+                }
+                hasDataPair &&
+                    usbInterface.interfaceClass == UsbConstants.USB_CLASS_CDC_DATA -> {
+                    preferredDataInterface = usbInterface
+                    preferredInEndpoint = inEndpoint
+                    preferredOutEndpoint = outEndpoint
+                }
+                hasDataPair && fallbackDataInterface == null -> {
+                    fallbackDataInterface = usbInterface
+                    fallbackInEndpoint = inEndpoint
+                    fallbackOutEndpoint = outEndpoint
+                }
+            }
+        }
+
+        val dataInterface = preferredDataInterface ?: fallbackDataInterface ?: return null
+        val inEndpoint = preferredInEndpoint ?: fallbackInEndpoint ?: return null
+        val outEndpoint = preferredOutEndpoint ?: fallbackOutEndpoint ?: return null
+        return PortConfig(preferredControlInterface, dataInterface, inEndpoint, outEndpoint)
+    }
+
+    private fun configureDevice(
+        connection: UsbDeviceConnection,
+        config: PortConfig,
+        baudRate: Int,
+    ) {
+        val control = config.controlInterface ?: return
+        val lineCoding =
+            byteArrayOf(
+                (baudRate and 0xFF).toByte(),
+                ((baudRate shr 8) and 0xFF).toByte(),
+                ((baudRate shr 16) and 0xFF).toByte(),
+                ((baudRate shr 24) and 0xFF).toByte(),
+                0, // stop bits: 1
+                0, // parity: none
+                8, // data bits
+            )
+
+                val lineCodingResult =
+            connection.controlTransfer(
+                UsbConstants.USB_DIR_OUT or
+                    UsbConstants.USB_TYPE_CLASS or
+                    usbRecipientInterface,
+                0x20,
+                0,
+                control.id,
+                lineCoding,
+                lineCoding.size,
+                1000,
+            )
+        if (lineCodingResult < 0) {
+            throw IllegalStateException("Failed to configure USB line coding")
+        }
+
+        val controlLineResult =
+            connection.controlTransfer(
+                UsbConstants.USB_DIR_OUT or
+                    UsbConstants.USB_TYPE_CLASS or
+                    usbRecipientInterface,
+                0x22,
+                0x0001, // DTR on, RTS off
+                control.id,
+                null,
+                0,
+                1000,
+            )
+        if (controlLineResult < 0) {
+            throw IllegalStateException("Failed to configure USB control line state")
+        }
+    }
+
+    private fun startReadLoop() {
+        val connection = usbConnection ?: return
+        val endpoint = usbInEndpoint ?: return
+
+        isReading = true
+        readThread =
+            Thread({
+                val packetSize = endpoint.maxPacketSize.coerceAtLeast(64)
+                val buffer = ByteArray(packetSize * 4)
+                try {
+                    while (isReading) {
+                        val bytesRead = connection.bulkTransfer(endpoint, buffer, buffer.size, 250)
+                        if (!isReading) {
+                            break
+                        }
+                        if (bytesRead <= 0) {
+                            continue
+                        }
+                        val packet = buffer.copyOf(bytesRead)
+                        mainHandler.post {
+                            eventSink?.success(packet)
+                        }
+                    }
+                } catch (error: Exception) {
+                    if (isReading) {
+                        mainHandler.post {
+                            eventSink?.error(
+                                "usb_io_error",
+                                error.message ?: "USB serial I/O error",
+                                null,
+                            )
+                        }
+                        scheduleCloseUsbConnection()
+                    }
+                }
+            }, "MeshCoreUsbRead").also { thread ->
+                thread.isDaemon = true
+                thread.start()
+            }
+    }
+
+    private fun writeToDevice(data: ByteArray) {
+        val connection = usbConnection ?: throw IllegalStateException("USB connection missing")
+        val endpoint = usbOutEndpoint ?: throw IllegalStateException("USB output endpoint missing")
+        var offset = 0
+        val maxPacketSize = endpoint.maxPacketSize.coerceAtLeast(64)
+        while (offset < data.size) {
+            val chunkSize = minOf(maxPacketSize, data.size - offset)
+            val chunk = data.copyOfRange(offset, offset + chunkSize)
+            val bytesWritten = connection.bulkTransfer(endpoint, chunk, chunkSize, 1000)
+            if (bytesWritten != chunkSize) {
+                throw IllegalStateException("Short USB write: wrote $bytesWritten of $chunkSize bytes")
+            }
+            offset += chunkSize
+        }
+    }
+
+    private fun scheduleCloseUsbConnection(onComplete: (() -> Unit)? = null) {
+        usbIoExecutor.execute {
+            closeUsbConnection()
+            if (onComplete != null) {
+                mainHandler.post(onComplete)
+            }
+        }
+    }
+
+    @Synchronized
+    private fun closeUsbConnection() {
+        isReading = false
+        readThread?.interrupt()
+        if (readThread != null && readThread !== Thread.currentThread()) {
+            try {
+                readThread?.join(300)
+            } catch (_: InterruptedException) {
+                Thread.currentThread().interrupt()
+            }
+        }
+        readThread = null
+
+        val connection = usbConnection
+        val claimedControl = controlInterface
+        val claimedData = dataInterface
+
+        usbInEndpoint = null
+        usbOutEndpoint = null
+        controlInterface = null
+        dataInterface = null
+        usbConnection = null
+
+        if (connection != null) {
+            if (claimedControl != null) {
+                try {
+                    connection.releaseInterface(claimedControl)
+                } catch (_: Exception) {
+                }
+            }
+            if (claimedData != null && claimedData.id != claimedControl?.id) {
+                try {
+                    connection.releaseInterface(claimedData)
+                } catch (_: Exception) {
+                }
+            }
+            try {
+                connection.close()
+            } catch (_: Exception) {
+            }
+        }
+        connectedDeviceName = null
+    }
+
+    private fun handleUsbDetached(intent: Intent) {
+        val detachedDevice =
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                intent.getParcelableExtra(UsbManager.EXTRA_DEVICE, UsbDevice::class.java)
+            } else {
+                @Suppress("DEPRECATION")
+                intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)
+            }
+
+        val detachedName = detachedDevice?.deviceName ?: return
+
+        if (pendingConnectPortName == detachedName) {
+            pendingConnectResult?.error(
+                "usb_device_detached",
+                "USB device was removed before the connection completed",
+                null,
+            )
+            pendingConnectResult = null
+            pendingConnectPortName = null
+        }
+
+        if (connectedDeviceName == detachedName) {
+            scheduleCloseUsbConnection {
+                eventSink?.error(
+                    "usb_device_detached",
+                    "USB device was disconnected",
+                    null,
+                )
+            }
+        }
+    }
+
+    private fun pendingIntentFlags(): Int {
+        var flags = PendingIntent.FLAG_UPDATE_CURRENT
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            flags = flags or PendingIntent.FLAG_MUTABLE
+        }
+        return flags
+    }
+}
@@ -1,3 +1,7 @@
 org.gradle.jvmargs=-Xmx8G -XX:MaxMetaspaceSize=4G -XX:ReservedCodeCacheSize=512m -XX:+HeapDumpOnOutOfMemoryError
 android.useAndroidX=true
 android.enableJetifier=true
+# This builtInKotlin flag was added automatically by Flutter migrator
+android.builtInKotlin=false
+# This newDsl flag was added automatically by Flutter migrator
+android.newDsl=false
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#e3e3e3"><path d="M268-240 42-466l57-56 170 170 56 56-57 56Zm226 0L268-466l56-57 170 170 368-368 56 57-424 424Zm0-226-57-56 198-198 57 56-198 198Z"/></svg>
@@ -21,7 +21,12 @@ The MeshCore BLE protocol implements a binary frame-based communication system u

 ### Connection Flow

-1. **Scan** for devices with name prefix `MeshCore-`
+1. **Scan** for devices with known name prefixes (defined in `MeshCoreUuids.deviceNamePrefixes`):
+    - `MeshCore-`
+    - `Whisper-`
+    - `WisCore-`
+    - `HT-`
+    - `LowMesh_MC_`
 2. **Connect** with 15-second timeout
 3. **Request MTU** of 185 bytes (falls back to default if unsupported)
 4. **Discover services** and locate NUS characteristics
@@ -0,0 +1,30 @@
+# MeshCore Open - Feature Documentation
+
+MeshCore Open is an open-source Flutter client for MeshCore LoRa mesh networking devices. This documentation covers every user-facing feature, how to access it, and what it does.
+
+## Table of Contents
+
+1. [Scanner & Connection](scanner-and-connection.md) - BLE scanning, USB serial, and TCP connection
+2. [Navigation](navigation.md) - App flow, device screen, and quick-switch navigation
+3. [Contacts](contacts.md) - Contact management, groups, discovery, and sharing
+4. [Chat & Messaging](chat-and-messaging.md) - Direct messages, message status, reactions, and retries
+5. [Channels](channels.md) - Broadcast channels, communities, and channel chat
+6. [Map & Location](map-and-location.md) - Node map, path tracing, line-of-sight, and offline caching
+7. [Settings](settings.md) - Device settings, app settings, radio configuration, and exports
+8. [Notifications](notifications.md) - System notifications, unread badges, and notification preferences
+9. [Repeater Management](repeater-management.md) - Repeater hub, status, CLI, telemetry, and neighbors
+10. [Additional Features](additional-features.md) - GIF picker, localization, debug logs, SMAZ compression, and more
+11. [BLE Protocol & Data Layer](ble-protocol.md) - Technical reference for the communication protocol and data architecture
+
+## App Overview
+
+MeshCore Open connects to MeshCore LoRa mesh radios over BLE, USB, or TCP. Once connected, users can:
+
+- **Chat** with other mesh nodes via encrypted direct messages
+- **Broadcast** on shared channels (public, hashtag, private, or community-scoped)
+- **View nodes on a map** with GPS locations, predicted positions, and path traces
+- **Manage repeaters** with CLI access, telemetry, neighbor info, and settings
+- **Share contacts** via `meshcore://` URIs and QR codes
+- **Configure radio settings** including frequency, power, bandwidth, and spreading factor
+- **Cache offline maps** for use without internet connectivity
+- **Analyze line-of-sight** between nodes with terrain elevation profiles
@@ -0,0 +1,262 @@
+# Additional Features
+
+## GIF Picker (Giphy Integration)
+
+### How to Access
+In any chat screen (direct or channel), tap the GIF button in the message input bar.
+
+### What the User Sees
+A bottom sheet with a search field and a grid of GIF thumbnails.
+
+### Key Interactions
+- On open, loads trending GIFs (G-rated, 25 results)
+- Type to search and press the keyboard submit button (search triggers on submit, not on each keystroke). Clearing the search field reloads trending GIFs
+- On network/API errors, a "Retry" button is shown in-place
+- Tap a GIF to select it — the chat input shows an inline preview with an X button to dismiss
+- Send the message to transmit the GIF reference (`g:<giphy-id>`)
+- Recipients see the GIF rendered inline via Giphy CDN
+- "Powered by Giphy" attribution is always shown at the bottom of the picker
+- The bottom sheet occupies 70% of screen height
+
+---
+
+## Localization / Multi-Language Support
+
+### How to Access
+App Settings → Appearance → Language
+
+### Supported Languages (18)
+English, French, Spanish, German, Polish, Slovenian, Portuguese, Italian, Chinese, Swedish, Dutch, Slovak, Bulgarian, Russian, Ukrainian, Hungarian, Japanese, Korean
+
+### How It Works
+- All UI strings go through Flutter's ARB localization system
+- Language can follow the system locale or be explicitly overridden
+- Changes take effect immediately
+
+---
+
+## Discovered Contacts Screen
+
+### How to Access
+From Contacts screen → overflow menu → "Discovered Contacts"
+
+### What the User Sees
+A list of nodes heard passively over the air but not yet added as contacts. Each shows:
+- Color-coded avatar (by type)
+- Name
+- Short public key
+- Last-seen time
+
+### Key Interactions
+- Search bar with debounced filtering
+- Sort by last seen or name; filter by type
+- **Tap**: Import the contact (adds to your contact list)
+- **Long-press**: Add Contact, Copy `meshcore://` URI to clipboard, or Delete
+- Overflow menu → "Delete All" (with confirmation)
+- Already-known contacts and your own node are filtered out
+
+---
+
+## SMAZ Compression
+
+### What It Is
+An optional per-contact and per-channel text compression feature using the SMAZ algorithm (optimized for short English text).
+
+### How to Enable
+- **Per contact**: Chat screen → info button → toggle "SMAZ compression"
+- **Per channel**: Long-press channel → Edit → toggle "SMAZ compression"
+
+### How It Works
+- When enabled, compression is applied using a "compress only if smaller" strategy — the message is only transmitted compressed if the encoded result is actually shorter than the original. Otherwise, the original text is sent uncompressed
+- Compressed messages are transmitted with a `s:` prefix followed by base64-encoded data
+- Recipients using MeshCore Open will decompress automatically. **Recipients using other software** that is not SMAZ-aware will see garbled `s:...` text
+- The codec operates on ASCII. Non-ASCII / non-English text generally does not benefit from compression and may even expand. Best suited for short English messages
+- Disabled by default
+
+---
+
+## Community QR Scanner
+
+### How to Access
+From Channels screen → "+" FAB → "Scan Community QR"
+
+### What the User Sees
+A live QR scanner view with instruction text overlay.
+
+### Key Interactions
+- Scan a community QR code shared by another member
+- On valid scan: confirmation dialog showing community name and ID
+- Option to "Add public channel to device" on join
+- If already a member: shows an "Already a member" dialog
+- Invalid QR: shows an orange error snackbar
+
+---
+
+## Channel Message Path Viewing
+
+### How to Access
+In a channel chat, tap a message bubble (mobile) or use the "Path" action (desktop).
+
+### What the User Sees
+- Summary card: sender, time, repeat count, path type, observed hops
+- "Other Observed Paths" section (if multiple paths detected)
+- "Repeater Hops" section listing each hop with hex prefix, resolved name, and GPS coordinates
+
+### Actions
+- **Radar icon**: Opens path trace map for live trace
+- **Map icon**: Opens a map with hop markers and polyline
+- **Path dropdown**: Switch between observed path variants (if multiple)
+
+---
+
+## Debug Logging
+
+### BLE Debug Log
+**Access**: Settings → BLE Debug Log
+
+Two views:
+- **Frames**: Each BLE frame with direction, description, hex preview, timestamp. Long-press to copy hex.
+- **Raw Log RX**: Decoded LoRa packets with route type, payload type, path bytes, and summary.
+
+### App Debug Log
+**Access**: Settings → App Debug Log (must be enabled first in App Settings → Debug)
+
+Structured log entries with level (Info/Warning/Error), tag, message, and timestamp.
+
+Both logs support copy-all and clear operations.
+
+---
+
+## Chrome Required Screen
+
+### When It Appears
+Automatically shown on web platforms when a non-Chromium browser is detected.
+
+### What the User Sees
+A full-screen informational page explaining that Web Bluetooth requires a Chromium-based browser. No interactive elements — purely informational.
+
+---
+
+## Path History Service
+
+### What It Does (Background Service)
+Maintains an in-memory LRU cache of up to 50 contacts, each with up to 100 route history entries, tracking:
+- Hop count and trip time
+- Success/failure counts and route weights
+- Flood vs. direct discovery
+
+### Path Scoring
+Paths are scored using a weighted formula: reliability (45%), route weight (20%), latency (25%), and freshness (10%). These weights are internal and not user-configurable. Paths whose weight drops to zero or below are automatically deleted. Flood deliveries that receive an ACK give a weight boost (+0.5) to the specific return path.
+
+Used internally for:
+- **Auto route rotation**: Cycles through known paths using configurable weights on retries, with a diversity window to avoid re-using recently tried paths
+- **Path selection**: Picks the best-scored path for each retry attempt
+- **Flood statistics**: Tracks flood vs. direct discovery ratios
+
+---
+
+## Message Retry Service
+
+### What It Does (Background Service)
+Handles reliable delivery of outgoing direct messages:
+1. Assigns a UUID and sends immediately. Only one message per contact can be in-flight at a time (avoids overflowing the firmware's 8-entry ACK table); subsequent messages are queued
+2. Listens for ACK frames matched via SHA-256 hash of `[timestamp][attempt][text][sender_pubkey]`
+3. On timeout, retries with exponential backoff: `1000 × 2^retryCount` ms (1s, 2s, 4s, 8s...)
+4. Each retry may use a different path (via path history diversity window)
+5. After max retries: marks failed but keeps a **30-second grace window** during which a late ACK can still resolve the message to "delivered". Optionally clears the contact's path
+6. Reports RTT and path data for quality learning
+7. Maintains an ACK hash history (last 50 entries) to handle duplicate ACKs
+
+### Configurable Settings (App Settings → Messaging)
+- Max retries (2–10, default 5)
+- Clear path on max retry (on/off)
+- Auto route rotation with weight parameters
+
+---
+
+## Timeout Prediction (ML)
+
+### What It Does (Background Service)
+An ML-based service that predicts expected delivery timeouts:
+- Collects delivery observations (path length, message size, time since last RX, delivery time) in a sliding window of up to 100 observations (oldest evicted first)
+- Requires **10 minimum observations** before first training. After that, retrains every 5 new observations
+- Applies a **1.5x safety margin** to raw predictions (the actual timeout issued is 1.5× the model's predicted delivery time)
+- Features with zero variance are automatically excluded from training
+- Blends per-contact statistics with ML predictions
+- Falls back to `3000 + 3000 × pathLength` ms when insufficient data
+- Observations are persisted to storage via a 2-second debounced timer (observations within 2s of app termination may be lost)
+
+---
+
+## On-Device Message Translation
+
+### What It Is
+An optional on-device translation service powered by an embedded LLM (llamadart, running GGUF models). Translation runs entirely on-device — no data leaves the app.
+
+### How to Access
+Tap the translate button on any received message. On first use, the GGUF model file is downloaded and cached locally.
+
+### How It Works
+- Model files are managed by `TranslationFileStore`; download progress is shown in-place
+- Before translating, the source language is automatically detected using the `flutter_langdetect` package. If the detected language already matches the target language, translation is skipped
+- Translation runs via `TranslationService` using the llamadart CPU backend (arm64 and x64 on Android)
+- Translated text is shown in `TranslatedMessageContent` as an inline overlay on the original message bubble
+- Each translation is cached; re-tapping shows the cached result without re-running inference
+
+---
+
+## Emoji Reactions
+
+### How to Access
+Long-press a message bubble in any direct or channel chat, then select a reaction emoji.
+
+### What the User Sees
+An emoji picker inline with common reactions. Selected reactions appear below the message bubble with a count.
+
+### How It Works
+- Implemented via `emoji_picker.dart` and `reaction_helper.dart`
+- Reactions are transmitted as a special message type visible to all participants with MeshCore Open
+
+---
+
+## Linkification
+
+### What It Does
+URLs and `meshcore://` URIs in received messages are automatically detected and rendered as tappable links.
+
+### How It Works
+- Powered by the `flutter_linkify` package via `link_handler.dart`
+- Tapping a URL opens the system browser; tapping a `meshcore://` URI imports the contact
+
+---
+
+## GPX Export
+
+### How to Access
+Settings → Export section (three options: Export Repeaters, Export Contacts, Export All).
+
+### What It Does
+Exports contacts with GPS coordinates to a `.gpx` file via the OS share sheet. Not available on web.
+
+---
+
+## Pinch-to-Zoom Chat Text
+
+### What It Does
+Users can pinch to scale all chat text up or down within a session.
+
+### How It Works
+- Implemented via `ChatTextScaleService` and `ChatZoomWrapper`
+- Scale range: 0.8× to 1.8×
+- The chosen scale persists across the session via the service
+
+---
+
+## Background Service (Android)
+
+### What It Does
+On Android, a foreground service (`background_service.dart`) keeps the BLE connection and message handling alive when the app is in the background. On other platforms this is a no-op.
+
+### User Impact
+- A persistent notification appears while the service is running
+- Messages are received and retry logic continues even when the app is not in the foreground
@@ -0,0 +1,259 @@
+# BLE Protocol & Data Layer
+
+This is a technical reference for the communication protocol and data architecture.
+
+## Transport Layer
+
+The app supports three transports, all sharing the same command/response protocol:
+
+| Transport | Method | Implementation |
+|---|---|---|
+| Bluetooth LE | Nordic UART Service (NUS) GATT | `flutter_blue_plus` |
+| USB Serial | Packet-framed serial | `MeshCoreUsbManager` |
+| TCP | Packet-framed socket | `MeshCoreTcpConnector` |
+
+### BLE (Nordic UART Service)
+
+- **Service UUID**: `6e400001-b5a3-f393-e0a9-e50e24dcca9e`
+- **RX Characteristic** (write to device): `6e400002-b5a3-f393-e0a9-e50e24dcca9e`
+- **TX Characteristic** (notify from device): `6e400003-b5a3-f393-e0a9-e50e24dcca9e`
+
+Raw `Uint8List` payloads are written directly to the RX characteristic. Writes use "write without response" if supported, falling back to "write with response".
+
+### USB and TCP Framing
+
+Both use a lightweight packet framing codec:
+
+```
+TX (host → device):  [0x3C][len_lo][len_hi][payload...]
+RX (device → host):  [0x3E][len_lo][len_hi][payload...]
+```
+
+- Frame start: `0x3C` (`<`) for outgoing, `0x3E` (`>`) for incoming
+- Length: 2-byte little-endian, payload only
+- Max payload: 172 bytes
+- TCP: `tcpNoDelay: true` (Nagle disabled), writes serialized to prevent interleaving
+
+## Connection State Machine
+
+```
+enum MeshCoreConnectionState {
+  disconnected,
+  scanning,
+  connecting,
+  connected,
+  disconnecting,
+}
+```
+
+## BLE Connection Lifecycle
+
+1. **Scan** with known name prefixes (defined in `MeshCoreUuids.deviceNamePrefixes`):
+    - `MeshCore-`
+    - `Whisper-`
+    - `WisCore-`
+    - `Seeed`
+    - `Lilygo`
+    - `HT-`
+    - `LowMesh_MC_`
+    - `NRF52`
+2. **Connect** with 15-second timeout (6 seconds on Linux)
+3. **Request MTU** 185 bytes (non-web only)
+4. **Discover services** and locate NUS
+5. **Enable TX notifications** (up to 3 attempts on native)
+6. **Subscribe** to TX characteristic for incoming frames
+7. **Initial sync**: device info query, time sync, channel sync
+
+## Auto-Reconnect (BLE Only)
+
+On unexpected disconnection, auto-reconnect with exponential backoff:
+- Delays: 1s, 2s, 4s, 8s, 16s, 30s, 30s...
+- Resets on successful connection
+- Disabled for manual disconnects
+- Not available for USB or TCP
+
+## Protocol Constants
+
+| Constant | Value | Description |
+|---|---|---|
+| Max frame size | 172 bytes | BLE/USB/TCP payload limit |
+| Public key size | 32 bytes | Ed25519 public key |
+| Max path size | 64 bytes | Maximum path data |
+| Max name size | 32 bytes | Maximum node name |
+| Max text payload | 160 bytes | Firmware `MAX_TEXT_LEN` |
+| App protocol version | 4 | Sent in device query |
+| Contact frame size | 148 bytes | Fixed-size contact record |
+
+## Command Codes (App → Device)
+
+| Code | Name | Description |
+|------|------|-------------|
+| 1 | CMD_APP_START | Announce app connection |
+| 2 | CMD_SEND_TXT_MSG | Send direct text message |
+| 3 | CMD_SEND_CHANNEL_TXT_MSG | Send channel text message |
+| 4 | CMD_GET_CONTACTS | Request contact list |
+| 5 | CMD_GET_DEVICE_TIME | Query device clock |
+| 6 | CMD_SET_DEVICE_TIME | Set device clock |
+| 7 | CMD_SEND_SELF_ADVERT | Broadcast own advertisement |
+| 8 | CMD_SET_ADVERT_NAME | Set node name |
+| 9 | CMD_ADD_UPDATE_CONTACT | Add or update a contact |
+| 10 | CMD_SYNC_NEXT_MESSAGE | Request next queued message |
+| 11 | CMD_SET_RADIO_PARAMS | Set radio parameters |
+| 12 | CMD_SET_RADIO_TX_POWER | Set TX power |
+| 13 | CMD_RESET_PATH | Reset contact path |
+| 14 | CMD_SET_ADVERT_LATLON | Set advertised location |
+| 15 | CMD_REMOVE_CONTACT | Remove a contact |
+| 16 | CMD_SHARE_CONTACT | Share contact to mesh |
+| 17 | CMD_EXPORT_CONTACT | Export contact as bytes |
+| 18 | CMD_IMPORT_CONTACT | Import contact from bytes |
+| 19 | CMD_REBOOT | Reboot device |
+| 20 | CMD_GET_BATT_AND_STORAGE | Query battery and storage |
+| 22 | CMD_DEVICE_QUERY | Query device info |
+| 26 | CMD_SEND_LOGIN | Login to repeater/room |
+| 27 | CMD_SEND_STATUS_REQ | Request repeater status |
+| 30 | CMD_GET_CONTACT_BY_KEY | Get contact by public key |
+| 31 | CMD_GET_CHANNEL | Get channel definition |
+| 32 | CMD_SET_CHANNEL | Set channel name and PSK |
+| 36 | CMD_SEND_TRACE_PATH | Request path trace |
+| 38 | CMD_SET_OTHER_PARAMS | Set misc parameters |
+| 39 | CMD_SEND_TELEMETRY_REQ | Request sensor telemetry |
+| 40 | CMD_GET_CUSTOM_VAR | Get custom variables |
+| 41 | CMD_SET_CUSTOM_VAR | Set a custom variable |
+| 50 | CMD_SEND_BINARY_REQ | Send binary request |
+| 56 | CMD_GET_STATS | Request companion radio stats |
+| 57 | CMD_SEND_ANON_REQ | Send anonymous request |
+| 58 | CMD_SET_AUTO_ADD_CONFIG | Set auto-add configuration |
+| 59 | CMD_GET_AUTO_ADD_CONFIG | Get auto-add configuration |
+| 61 | CMD_SET_PATH_HASH_MODE | Set path hash width (bytes per hop) |
+
+## Response / Push Codes (Device → App)
+
+| Code | Name | Description |
+|------|------|-------------|
+| 0 | RESP_CODE_OK | Generic success |
+| 1 | RESP_CODE_ERR | Generic error |
+| 2 | RESP_CODE_CONTACTS_START | Contact list begins |
+| 3 | RESP_CODE_CONTACT | Single contact data |
+| 4 | RESP_CODE_END_OF_CONTACTS | Contact list complete |
+| 5 | RESP_CODE_SELF_INFO | Device self-info response |
+| 6 | RESP_CODE_SENT | Message transmitted; carries `[1]=is_flood, [2–5]=ack_hash, [6–9]=estimated_timeout_ms` |
+| 7 | RESP_CODE_CONTACT_MSG_RECV | Incoming direct message (v2) |
+| 8 | RESP_CODE_CHANNEL_MSG_RECV | Incoming channel message (v2) |
+| 10 | RESP_CODE_NO_MORE_MESSAGES | No more queued messages |
+| 11 | RESP_CODE_EXPORT_CONTACT | Exported contact data |
+| 9 | RESP_CODE_CURR_TIME | Current device time |
+| 12 | RESP_CODE_BATT_AND_STORAGE | Battery mV (uint16 LE) + storage used/total (uint32 LE each) |
+| 13 | RESP_CODE_DEVICE_INFO | Firmware info |
+| 16 | RESP_CODE_CONTACT_MSG_RECV_V3 | Incoming direct message (v3) |
+| 17 | RESP_CODE_CHANNEL_MSG_RECV_V3 | Incoming channel message (v3) |
+| 18 | RESP_CODE_CHANNEL_INFO | Channel definition |
+| 21 | RESP_CODE_CUSTOM_VARS | Custom variables |
+| 24 | RESP_CODE_STATS | Companion radio stats |
+| 25 | RESP_CODE_AUTO_ADD_CONFIG | Auto-add flags |
+| 0x80 | PUSH_CODE_ADVERT | Known contact re-seen |
+| 0x81 | PUSH_CODE_PATH_UPDATED | Better path found; carries the 32-byte public key of the updated contact |
+| 0x82 | PUSH_CODE_SEND_CONFIRMED | Delivery ACK from remote; carries ACK hash (4 bytes) + trip time (4 bytes) |
+| 0x83 | PUSH_CODE_MSG_WAITING | Offline messages queued |
+| 0x85 | PUSH_CODE_LOGIN_SUCCESS | Repeater/room login succeeded |
+| 0x86 | PUSH_CODE_LOGIN_FAIL | Repeater/room login failed |
+| 0x87 | PUSH_CODE_STATUS_RESPONSE | Repeater status response |
+| 0x88 | PUSH_CODE_LOG_RX_DATA | Radio RX data with SNR (int8, units 1/4 dB), RSSI, and raw radio packet |
+| 0x89 | PUSH_CODE_TRACE_DATA | Path trace result |
+| 0x8A | PUSH_CODE_NEW_ADVERT | New node discovered |
+| 0x8B | PUSH_CODE_TELEMETRY_RESPONSE | Sensor telemetry data |
+| 0x8C | PUSH_CODE_BINARY_RESPONSE | Binary data response |
+
+## Data Models
+
+### Contact
+32-byte public key (primary identity), name, type (chat/repeater/room/sensor), flags, path data, GPS coordinates, last-seen timestamp. Parsed from 148-byte firmware frames with this layout:
+
+```
+[0]     = resp_code
+[1–32]  = public key (32 bytes)
+[33]    = type (1=chat, 2=repeater, 3=room, 4=sensor)
+[34]    = flags (bit 0 = favorite)
+[35]    = path_length
+[36–99] = path (64 bytes)
+[100–131] = name (32 bytes, null-padded)
+[132–135] = timestamp (uint32 LE)
+[136–139] = latitude (int32 LE, × 1e-6 degrees)
+[140–143] = longitude (int32 LE, × 1e-6 degrees)
+[144–147] = last_modified (uint32 LE)
+```
+
+### Message (Direct)
+Sender key, text, timestamp, outgoing flag, status (pending/sent/delivered/failed), message ID (UUID), retry count, ACK hash, trip time, path data, reactions.
+
+### Channel Message
+Sender name, text, timestamp, status (pending/sent/failed), repeater hops, path variants, channel index, reactions, reply threading fields.
+
+### Channel
+Index (0–7), name, 16-byte PSK, unread count. PSK derivation methods for hashtag (SHA-256) and community (HMAC-SHA256) channels.
+
+### Community
+UUID, name, 32-byte secret, hashtag channel list. Shared via QR code.
+
+## Persistence
+
+All data is stored via `SharedPreferences` (JSON-serialized). No SQLite or other database.
+
+| Data | Storage Key Pattern | Scope |
+|---|---|---|
+| Contacts | `contacts<pubKey10>` | Per device identity |
+| Messages | `messages_<pubKey10><contactKey>` | Per device + contact |
+| Channel Messages | `channel_messages_<pubKey10><index>` | Per device + channel |
+| Channels | `channels<pubKey10>` | Per device identity |
+| Channel Order | `channel_order_<pubKey10>` | Per device identity |
+| Contact Groups | `contact_groups<pubKey10>` | Per device identity |
+| Communities | `communities_v1<pubKey10>` | Per device identity |
+| Unread Counts | `contact_unread_count<pubKey10>` | Per device identity |
+| Discovered Contacts | `discovered_contacts` | Global |
+| App Settings | `app_settings` | Global |
+| Path History | `path_history_<contactKey>` | Per contact |
+
+## Auto-Add Configuration Bitmask
+
+Used by `CMD_SET_AUTO_ADD_CONFIG` (58) and `RESP_CODE_AUTO_ADD_CONFIG` (25):
+
+| Bit | Flag | Description |
+|-----|------|-------------|
+| 0 | 0x01 | Overwrite oldest contact when list is full |
+| 1 | 0x02 | Auto-add chat users |
+| 2 | 0x04 | Auto-add repeaters |
+| 3 | 0x08 | Auto-add room servers |
+| 4 | 0x10 | Auto-add sensors |
+
+## Radio Packet Payload Types
+
+Seen inside `PUSH_CODE_LOG_RX_DATA` raw packets:
+
+| Code | Type |
+|------|------|
+| 0x00 | REQ (request) |
+| 0x01 | RESPONSE |
+| 0x02 | TXTMSG (text message) |
+| 0x03 | ACK |
+| 0x04 | ADVERT |
+| 0x05 | GRPTXT (group/channel text) |
+| 0x06 | GRPDATA (group data) |
+| 0x07 | ANONREQ (anonymous request) |
+| 0x08 | PATH |
+| 0x09 | TRACE |
+| 0x0A | MULTIPART |
+| 0x0B | CONTROL |
+| 0x0F | RAW_CUSTOM |
+
+## State Management
+
+Uses Flutter `Provider` with `ChangeNotifier`. The central state holder is `MeshCoreConnector`, which owns all in-memory collections and fires debounced (50ms) `notifyListeners()` to update the UI. In-memory conversations are windowed to 200 messages per contact; older messages remain on disk and are loaded on demand.
+
+### Data Flow
+
+1. Raw frames arrive over BLE/USB/TCP
+2. First byte is parsed as response/push code
+3. Appropriate model factory (`fromFrame()`) parses the data
+4. In-memory collections are updated
+5. Storage stores are persisted (async)
+6. `notifyListeners()` triggers UI rebuilds
+7. Screens read current state via getters
@@ -0,0 +1,154 @@
+# Channels
+
+## Overview
+
+Channels are broadcast group-chat spaces secured by a 16-byte pre-shared key (PSK). Any device with the same channel index and PSK will receive and decrypt channel messages. Unlike direct messages, channel messages are broadcast to the entire mesh.
+
+The number of active channels is determined by the firmware (default 40); the device reports its actual limit at login.
+
+## How to Access
+
+QuickSwitchBar tab 1 (middle) from any main screen.
+
+## Channel Types
+
+| Type | Icon | Color | Description |
+|---|---|---|---|
+| Public | Globe | Green | Fixed well-known PSK; any device can join |
+| Hashtag | Hash tag | Blue | PSK derived from the hashtag name via SHA-256; discoverable by convention |
+| Private | Lock | Blue | Random PSK; requires out-of-band sharing of the 32-hex key |
+| Community | Groups/Tag | Magenta | PSK derived via HMAC-SHA256 from a community's shared secret |
+
+## Channels List Screen
+
+### What the User Sees
+
+- **Search bar** with live text filtering (300ms debounce)
+- **Sort/filter button**
+- **Scrollable list of channel cards**, each showing:
+  - Type icon with color coding (magenta badge overlay for community channels)
+  - Channel name (or "Channel N" if unnamed)
+  - Unread badge (if messages are unread)
+  - Drag handle (when manual sort is active)
+- **"+" FAB** to add a new channel
+- **Overflow menu**: Disconnect, Manage Communities, Settings
+
+If no channels exist, an empty state with an "Add Public Channel" shortcut is shown. If a search produces no results, a separate "no results" empty state with a search-off icon is shown.
+
+Pull-to-refresh (swipe down) forces a re-fetch of channels from the device firmware.
+
+### Sorting Options
+
+- **Manual** (default): Drag-and-drop reordering, persisted (drag handles are hidden when a search query is active)
+- **A–Z**: Alphabetical
+- **Latest messages**: Most recent first
+- **Unread**: Most unread first
+
+## Adding a Channel
+
+Tap the "+" FAB to open a dialog with six options:
+
+1. **Create Private Channel** — Enter a name (max 31 characters); a random PSK is generated
+2. **Join Private Channel** — Enter a name and a 32-hex PSK (non-hex characters like spaces and dashes are silently stripped, so pasted keys with formatting are accepted)
+3. **Join Public Channel** — One tap; uses the well-known public PSK (only shown if no public channel exists)
+4. **Join Hashtag Channel** — Enter a hashtag name; PSK is derived from the name. If communities exist, choose between regular hashtag (SHA-256) or community hashtag (HMAC)
+5. **Scan Community QR** — Opens QR scanner to join a community
+6. **Create Community** — Enter a name; generates a random 32-byte secret; optionally adds a community public channel; shows QR code for sharing
+
+## Channel Actions (Long-Press / Right-Click)
+
+| Action | Description |
+|---|---|
+| Edit | Change name, PSK (with a dice icon to generate a random PSK), SMAZ compression toggle (compresses outgoing messages to allow longer text within the byte limit), or Cyr2Lat encoding toggle (transliterates Cyrillic to Latin for compatibility) |
+| Mute / Unmute | Toggle push notification suppression for this channel |
+| Delete | Remove the channel from the device (confirmation required) |
+
+## Channel Chat
+
+Tap a channel card to open the channel chat screen.
+
+### App Bar
+
+- Type icon: globe for public channels, tag (#) for all other channel types
+- Channel name
+- Subtitle: "{Public|Private} • {N} unread" (e.g., "Public • 3 unread")
+
+### Message Display
+
+- Reverse-scrolling list (newest at bottom)
+- **Incoming messages**: Colored avatar with sender's initial (or first emoji if name starts with one; color is deterministic from sender name hash), sender name in primary color, message bubble
+- **Outgoing messages**: Primary container color bubble with a small status icon: pending (clock), sent (checkmark), or failed (red error circle)
+- Automatic older-message loading on scroll-to-top
+- Jump-to-bottom button when scrolled up
+- **Pinch-to-zoom**: Two-finger zoom (0.8x–1.8x) and double-tap to reset text size
+- **Message tracing mode** (when enabled in App Settings): Each bubble additionally shows path prefix bytes (`via XX,YY,...`), a timestamp, and a repeat count icon
+
+### Message Types in Chat
+
+- **Plain text** with linkified URLs
+- **GIFs** (`g:{gifId}`) rendered inline via Giphy CDN
+- **Location pins** (`m:{lat},{lon}|{label}|`) shown as tappable location cards
+- **Reactions** displayed as emoji pills below target messages
+
+### Replies (Channel Chat Only)
+
+- **Mobile**: Swipe an **incoming** message left to trigger reply (with haptic feedback). You cannot swipe your own outgoing messages. Swipe reply is not available on desktop.
+- **All platforms**: Long-press → "Reply"
+- Reply banner appears above the input bar with the quoted message (tap X to cancel)
+- Sent replies are prefixed `@[{senderName}] {text}`
+- Received replies show a bordered quote block inside the bubble; tapping scrolls to the original. Reply previews render GIF thumbnails and location pin icons, not just text.
+
+### Message Path Viewing
+
+- **All platforms**: Long-press (or right-click on desktop) a message bubble → "Path"
+- Opens the Channel Message Path Screen (see [Additional Features](additional-features.md))
+
+### Context Actions (Long-Press / Right-Click)
+
+| Action | Availability | Description |
+|---|---|---|
+| Reply | All messages | Triggers reply mode |
+| Path | All messages | Opens message path view |
+| Add Reaction | Incoming messages only | Opens emoji picker (cannot react to your own messages) |
+| Copy | All messages | Copies text to clipboard |
+| Mark as Unread | Incoming messages only | Marks this message and all subsequent incoming messages as unread |
+| Delete | All messages | Removes locally (not from mesh) |
+
+## Communities
+
+Communities are a layer above channels that provide a private namespace.
+
+### What is a Community?
+
+A community has a name and a 32-byte random secret. Channel PSKs are derived from this secret:
+- **Public channel**: `HMAC-SHA256(secret, "channel:v1:__public__")[:16]`
+- **Hashtag channel**: `HMAC-SHA256(secret, "channel:v1:{hashtag}")[:16]`
+
+Outsiders who don't know the secret cannot discover or join community channels.
+
+### Sharing a Community
+
+Communities are shared via QR codes containing a JSON payload:
+```json
+{"v": 1, "type": "meshcore_community", "name": "...", "k": "<base64url-secret>"}
+```
+
+### Managing Communities
+
+From the channels screen overflow menu → "Manage Communities". Opens a draggable scrollable sheet (resizable 30–90% of screen height):
+
+- Each community shows its name and a short community ID (first 8 hex characters)
+- **Tap a community** to directly show its QR code for sharing
+- **Popup menu** per community:
+  - **Show QR** — displays the QR code for sharing with new members
+  - **Leave Community** — removes the community locally and deletes all associated device channels (confirmation dialog warns how many channels will be removed)
+
+## How Channels Differ from Direct Messages
+
+| Aspect | Channels | Direct Messages |
+|---|---|---|
+| Addressing | Broadcast to all nodes with matching PSK | Point-to-point to a specific contact |
+| Encryption | Shared PSK (symmetric) | Contact's public key (asymmetric) |
+| Sender identity | Plain text prefix in payload | Verified via public key |
+| Replies | Supported (swipe or long-press) | Not supported |
+| Retry mechanism | No automatic retry | Exponential backoff with path rotation |
@@ -0,0 +1,121 @@
+# Chat & Messaging
+
+## Overview
+
+The app supports two chat modes:
+- **Direct messages**: Encrypted point-to-point messages to individual contacts
+- **Channel messages**: Broadcast messages to shared channels (see [Channels](channels.md))
+
+This page covers direct messaging. For channel chat, see the Channels documentation.
+
+## How to Access
+
+From the Contacts screen, tap any Chat-type contact to open the ChatScreen.
+
+## Chat Screen Layout
+
+### App Bar
+
+- **Title**: Contact name
+- **Subtitle**: Current routing path label (e.g., "2 hops", "flood (auto)", "direct (forced)") and unread count. Tapping the subtitle shows the full path details.
+- **Action button**:
+  - **Overflow menu** (⋮ icon): Contains Routing, Info, Telemetry, Settings, and Clear Chat. Routing opens the routing sheet where you can switch between Auto, Direct, and Flood routing and manage recent paths (hop count, round-trip time, age, success count, color-coded by repeater). Info shows a dialog with contact type, path, GPS coordinates, and public key.
+
+### Message List
+
+- Scrollable list with newest messages at the bottom
+- **Outgoing messages**: Right-aligned, primary color background. **Failed messages** change to a red-toned error container background
+- **Incoming messages**: Left-aligned, grey background with a colored avatar (initial letter or first emoji of sender name; color is deterministic from a hash of the sender name)
+- Bubble width capped at 72% of screen width
+- Hyperlinks rendered as tappable green underlined text
+- **Pinch-to-zoom**: Two-finger zoom (0.8x–1.8x) and double-tap to reset
+- **Jump to bottom**: Floating button appears when scrolled away from the bottom
+- **Lazy loading**: Scrolling to top loads older messages from storage
+
+### Input Bar
+
+- **GIF button** (left): Opens GIF picker bottom sheet
+- **Translation button** (optional, between GIF and text field): Shown only when translation is enabled in App Settings. Tap to configure outgoing-message translation language and on/off toggle.
+- **Text field** (center): Auto-capitalization, enforces UTF-8 byte limit in real-time
+- **Send button** (right): Submits the message
+- On desktop: Enter/Numpad Enter also submits
+- When a GIF is selected, the text field shows an inline GIF preview with a dismiss button
+
+## Message Types
+
+| Type | Wire Format | Display |
+|---|---|---|
+| Plain text | Raw UTF-8 string | Inline text with link detection |
+| GIF | `g:<giphy-id>` | Inline GIF image from Giphy CDN |
+| Location pin | `m:<lat>,<lon>\|<label>\|...` | Location icon + label; tap to open map |
+| Reaction | `r:<hash>:<emoji-index>` | Applied to target message as emoji pill |
+
+## Message Status
+
+Outgoing messages display a status indicator:
+
+| Status | Icon | Meaning |
+|---|---|---|
+| Pending | Grey double-check | Queued, waiting for device to transmit (visually identical to Sent) |
+| Sent | Grey double-check | Device confirmed transmission (visually identical to Pending) |
+| Delivered | Green double-check | Remote node acknowledged receipt |
+| Failed | Red X | All retries exhausted |
+
+### Message Tracing Mode
+
+When enabled in App Settings, additional metadata appears inside each bubble:
+- Timestamp (HH:MM)
+- Retry count (e.g., "Retry 2 of 4") — only shown for outgoing messages where at least one retry has occurred
+- Status icon (outgoing only)
+- Round-trip time in seconds (if delivered)
+
+## Message Length Limits
+
+- **Direct messages**: 156 bytes (UTF-8) — enforced in real-time by the input formatter
+- **Channel messages**: 160 minus sender name length minus 2 bytes for the `"<name>: "` prefix
+- Over-length paste shows a snackbar error
+
+## Send Queue
+
+Only one message per contact can be in-flight at a time (to avoid overflowing the firmware's 8-entry ACK table). If you send multiple messages rapidly, they are queued and sent sequentially — each waits for the previous one to be delivered, fail, or exhaust retries before transmitting.
+
+## Retry Mechanism
+
+When a direct message is sent:
+
+1. The app computes an expected ACK hash: `SHA256([timestamp][attempt][text][selfPubKey])[0:4]` — matching the firmware's hash calculation. If SMAZ compression is enabled, the compressed text (not the original) is hashed
+2. On device acknowledgment (`RESP_CODE_SENT`), the message transitions to "sent" and a timeout timer starts
+3. **Timeout duration**: Preferably from the ML timeout prediction service; otherwise from the device's own `est_timeout` in `RESP_CODE_SENT` (clamped to the physics range); otherwise calculated from LoRa airtime physics: `500 + (airtime × 6 + 250) × (pathLength + 1)` ms for direct paths, `500 + 16 × airtime` ms for flood (airtime is estimated from the radio's current spreading factor, bandwidth, and coding rate). The result is capped at 45 seconds.
+4. On timeout, the message is retried with **exponential backoff**: `1000 × 2^retryCount` ms (1s, 2s, 4s, 8s, 16s...)
+5. **Max retries**: Configurable (default 5, range 2–10)
+6. After max retries, the message is marked "failed" — but a **30-second grace window** remains during which a late ACK can still resolve the message to "delivered"
+7. If **Clear Path on Max Retry** is enabled (App Settings), the contact's stored routing path is automatically cleared when max retries are exhausted
+8. **Auto route rotation**: When enabled (and no manual path override is set), the retry service uses a diversity window to avoid re-using recently tried paths, cycling through known routes on each attempt
+
+### Manual Retry
+
+Long-press a failed message → "Retry" to re-send using the current routing settings.
+
+## Reactions
+
+Add emoji reactions to incoming messages (not your own):
+
+1. Long-press (or right-click on desktop) a message
+2. Select "Add reaction" from the context menu
+3. Choose from quick emojis (thumbs up, heart, laugh, party, clap, fire) or browse the full emoji picker
+4. Reactions appear as pills below the message bubble with emoji and count
+5. Pending reactions show at 50% opacity with a spinner
+6. Failed reactions show a red retry icon (tap to retry)
+
+## Context Actions (Long-Press / Right-Click)
+
+| Action | Availability | Description |
+|---|---|---|
+| Add reaction | Incoming messages only | Opens emoji picker |
+| View path | All platforms: long-press/right-click menu | Shows message routing path |
+| Copy | All messages | Copies text to clipboard |
+| Translate | Incoming messages only (when translation is enabled and not yet translated) | Translates the message on-demand using the on-device model |
+| Mark as Unread | Incoming messages only | Marks this message and all subsequent incoming messages as unread |
+| Delete | All messages | Removes locally (not from mesh) |
+| Retry | Failed outgoing messages | Re-sends the message |
+| Open chat with sender | Room server chats | Opens 1:1 chat with the message sender |
@@ -0,0 +1,118 @@
+# Contacts
+
+## Overview
+
+The Contacts screen is the primary hub for managing mesh nodes your radio has a relationship with. A "contact" is any node whose cryptographic advertisement has been received — it can be a chat user, repeater, room server, or sensor.
+
+## How to Access
+
+- QuickSwitchBar tab 0 (leftmost) from Channels or Map screens (Channels is shown first after connecting)
+- Back navigation from Chat or Settings screens
+
+## Contact Types
+
+| Type | Avatar Color | Icon | Description |
+|---|---|---|---|
+| Chat | Blue | Initials / emoji | Another user's mesh radio |
+| Repeater | Amber | Cell tower | A mesh repeater/relay node |
+| Room | Magenta | Meeting room | A room server for group chat |
+| Sensor | Teal | Sensors | A sensor device |
+
+## Contact List
+
+Each contact is displayed as a list tile showing:
+
+- **Avatar**: Color-coded circle with type icon (or first emoji of the contact's name if it starts with one)
+- **Name**: Contact name (single line)
+- **Path label**: "Direct", "N hops", or "Flood" (with forced variants if a path override is active)
+- **Public key**: Shortened hex format `<XXXXXXXX...XXXXXXXX>`
+- **Unread badge**: Red pill with count (if unread messages exist)
+- **Last seen**: Relative timestamp ("Now", "5 mins ago", "2 hours ago", "3 days ago"). For chat contacts, this shows whichever is more recent: the last advertisement time or the last message time
+- **Favorite star**: Amber star icon if favorited
+- **Location pin**: Grey pin icon if the contact has GPS coordinates
+
+Pull-to-refresh re-fetches the full contact list from the device.
+
+## Search and Filter
+
+A toolbar at the top provides:
+
+**Search**: Matches contact name (case-insensitive) or public key hex prefix. Debounced at 300ms.
+
+**Sort options**:
+- Latest Messages (by most recent message)
+- Heard Recently (by last seen / last message)
+- A–Z (alphabetical)
+
+**Filter options**:
+- All, Favorites, Users, Repeaters, Room Servers, Unread Only
+
+## Contact Groups
+
+Groups are a client-side organizational feature for grouping contacts.
+
+- **Create a group**: Tap the group dropdown → "+" icon → enter name → select members → Save
+- **Edit a group**: Group dropdown → pencil icon next to the group
+- **Delete a group**: Group dropdown → trash icon next to the group
+- **Filter by group**: Select a group from the dropdown to show only its members
+
+Groups are stored per radio identity (scoped by public key).
+
+**Validation rules**: Group names cannot be empty, cannot be "all" (reserved, case-insensitive), and must be unique (case-insensitive). The group creation dialog includes a built-in search field to filter contacts when selecting members. Creating a new group automatically selects it as the active filter.
+
+## Tap Actions
+
+| Contact Type | Action on Tap |
+|---|---|
+| Chat / Sensor | Opens ChatScreen for direct messaging |
+| Repeater | Shows password login dialog → opens RepeaterHubScreen |
+| Room | Shows password login dialog → opens ChatScreen for room chat |
+
+## Long-Press / Right-Click Menu
+
+| Action | Availability | Description |
+|---|---|---|
+| Ping | Repeaters only | Opens PathTraceMapScreen targeting the repeater |
+| Path Trace | Rooms (always); Chat/Sensor only if `pathLength > 0` | Opens PathTraceMapScreen. For rooms, label shows "Ping" when no path bytes are known, "Path Trace" when path bytes are available |
+| Manage Repeater | Repeaters only | Login dialog → RepeaterHubScreen |
+| Room Login | Rooms only | Login dialog → ChatScreen |
+| Room Management | Rooms only | Login dialog → RepeaterHubScreen (management mode) |
+| Add/Remove Favorite | All types | Toggles the favorite flag |
+| Share Contact | All types | Requests advert from device → copies `meshcore://<hex>` URI to clipboard |
+| Share Contact Zero-Hop | All types | Broadcasts the contact's advertisement one hop |
+| Delete Contact | All types | Confirmation dialog → removes from device and clears messages |
+
+## App Bar Menus
+
+The Contacts screen has a single **three-dot overflow menu** (`⋮`) in the app bar:
+
+- Discovered Contacts — opens the DiscoveryScreen
+- Add Contact from Clipboard — reads a `meshcore://<hex>` URI from clipboard and imports it
+- *(divider)*
+- Zero-Hop Advert — broadcasts your advertisement to immediately adjacent nodes
+- Flood Advert — broadcasts across the full mesh network
+- Copy Advert to Clipboard — copies your `meshcore://<hex>` URI for sharing externally
+- *(divider)*
+- Disconnect — disconnects from the device
+- Settings — opens the Settings screen
+
+A **floating action button** (person-add icon) provides a shortcut sheet to "Add Contact from Clipboard" or "Discovered Contacts".
+
+## Adding Contacts
+
+### Automatic (Passive)
+When the radio hears an advertisement, the contact appears automatically if auto-add is enabled for that type (configurable in Settings → Contact Settings).
+
+### Import from Clipboard
+Overflow menu (or the FAB shortcut) → "Add Contact from Clipboard". Reads a `meshcore://<hex>` URI from clipboard and imports it to the device.
+
+### Import from Discovered Contacts
+Overflow menu → "Discovered Contacts". Shows nodes heard passively that haven't been added yet. Tap to immediately import (no confirmation dialog), or long-press for more options (Copy URI, Delete). The Discovery screen has its own search bar, type filters (Users, Repeaters, Rooms), and sort options (Last Seen, A-Z). An overflow "Delete All" option clears all discovered contacts.
+
+## Contact Sharing Format
+
+Contacts are shared using the `meshcore://` URI scheme:
+```
+meshcore://<hex-encoded-advertisement-packet>
+```
+This contains the node's public key and metadata. Paste it into another MeshCore app to import.
@@ -0,0 +1,193 @@
+# Map & Location
+
+## Overview
+
+The Map feature is a full-featured node-location visualization and radio-planning tool built on OpenStreetMap tiles. It is one of the three primary views accessible from the QuickSwitchBar.
+
+## How to Access
+
+- **QuickSwitchBar tab 2** (rightmost) from Contacts or Channels
+- **Deep-link from a chat message**: Tapping a shared location pin in a chat opens the map centered on that pin
+- **Settings → Offline Map Cache**: Opens the tile cache management screen
+
+## What the Map Displays
+
+### Self Location (Teal Circle)
+Your own node's position, obtained from the device firmware. Displayed as a teal `person_pin_circle` icon. Only appears if the device has GPS data or a manually-set location.
+
+### Contact / Node Markers (Color-Coded)
+All contacts with known GPS coordinates are plotted:
+
+| Type | Color | Icon |
+|---|---|---|
+| Chat user | Blue | Person |
+| Repeater | Green | Router |
+| Room | Purple | Meeting room |
+| Sensor | Orange | Sensors |
+
+Node name labels appear automatically at zoom level 14 and above.
+
+### Shared Map Pins (Flag Icons)
+Location pins shared in chat messages are displayed as flags:
+- **Blue flag**: From a direct message
+- **Purple flag**: From a private channel
+- **Orange flag**: From a public channel
+
+Tap a pin to see its info. Options to "Hide" (session only) or "Remove" (persistent).
+
+### Predicted / Guessed Locations
+
+Many contacts on the mesh don't have GPS hardware, so the map has no explicit coordinates for them. Instead of leaving these contacts invisible, the app **infers an approximate position** by analyzing the repeater path the contact's messages travel through. These inferred positions are displayed as markers with a `not_listed_location` icon and a muted grey or colored border, visually distinct from confirmed-location markers.
+
+#### Why guessed locations exist
+
+In a mesh network, every message hops through one or more repeaters on its way to the destination. Each repeater in the path is identified by the first byte of its public key. If any of those repeaters have a known GPS location (because they advertise it), then a contact that routes through those repeaters must be somewhere within radio range of them. By combining the positions of multiple repeaters a contact is known to use, the app can triangulate a rough area where the contact is likely located.
+
+#### How the algorithm works
+
+1. **Build a repeater index**: The app collects all known contacts of type Repeater that have a valid GPS position and indexes them by the first byte of their public key.
+
+2. **Collect anchor points**: For each contact that lacks GPS, the app looks at the **last-hop byte** of the contact's current path and also searches the `PathHistoryService` for recent paths. Each last-hop byte that matches a located repeater becomes an "anchor point" — a GPS coordinate the contact is likely near.
+
+3. **Resolve ambiguity**: If multiple repeaters share the same first public-key byte (a hash collision), that byte is discarded as ambiguous. Only unambiguous one-to-one matches are kept.
+
+4. **Filter geometric inconsistencies**: Two anchor points separated by more than `2 × maxRangeKm` (the estimated LoRa radio range, computed from the current frequency, bandwidth, spreading factor, and TX power using a free-space path loss model) cannot both be in range of the same node. Outlier anchors are removed to keep only a geometrically consistent set.
+
+5. **Compute the estimated position**:
+   - **Single anchor**: The contact is placed on a small circle (330m radius) around the repeater. The angle on the circle is deterministic — derived from an FNV-1a hash of the contact's public key — so the same contact always appears at the same offset, preventing markers from stacking on top of each other.
+   - **Two or more anchors**: The position is a weighted average of all anchor coordinates (each subsequent anchor weighted at half the previous one, biasing toward the first), with a smaller offset radius (120m for 2 anchors, 80m for 3+) applied for visual separation.
+
+6. **Assign confidence level**:
+   - **High confidence** (2+ anchors): The marker border uses the node's type color (brighter border).
+   - **Low confidence** (1 anchor): The marker border is rendered in a muted grey.
+
+7. **Cache the result**: The computation is cached using a key derived from the contact's paths, anchor positions, path-history version, and radio parameters. The cache is only invalidated when any of these inputs change, avoiding recomputation on every UI rebuild.
+
+#### How to read guessed locations on the map
+
+- **Marker with `not_listed_location` icon**: This is a guessed position, not a confirmed GPS fix.
+- **Colored border** (type color): Higher confidence — the contact was seen through 2 or more repeaters with known positions.
+- **Grey border**: Lower confidence — based on a single repeater anchor only.
+- Coordinates shown in the marker info dialog are prefixed with `~` to indicate they are estimated.
+- Guessed locations can be toggled on/off in the map filter dialog (FAB → "Guessed locations" toggle).
+
+## Map Interactions
+
+### Zoom and Pan
+Standard pinch-to-zoom (range 2–18). Initial camera position is calculated from the statistical spread of all plotted points.
+
+### Tap on a Node Marker
+Opens a dialog showing: type, path (hop chain), coordinates, last-seen time, and public key. Action buttons vary by type:
+- **Chat nodes**: "Open Chat"
+- **Repeaters**: "Manage Repeater"
+- **Rooms**: "Join Room"
+
+### Long-Press on Empty Map Area
+Shows a bottom sheet with:
+- **Share marker here**: Prompts for a label, then pick a DM contact or channel to send the location to. Wire format: `m:<lat>,<lon>|<label>|poi`
+- **Set as my location**: Updates your device's advertised location
+
+### Filter Dialog (FAB)
+Toggle visibility of: chat nodes, repeaters, other nodes, guessed locations, discovery contacts, overlapping markers (stacked markers at similar coordinates), and shared map pins (flag markers).
+Additional filters:
+- **Key prefix filter**: Show only contacts whose public key starts with a given prefix
+- **Last-seen time slider**: Exponential scale from near-zero to 6 months, with "all time" at the top end
+
+### Legend Card (Top-Right)
+Shows node count and pin count. Tappable to expand a legend of all marker types.
+
+---
+
+## Path Trace Map
+
+### How to Access
+- From the main map's radar icon
+- From a contact's long-press menu → "Path Trace / Ping"
+- From a message's path view → radar icon
+
+### What the User Sees
+A map with a polyline showing the route from your node through repeater hops to the target:
+- **Green circles**: Hops with known GPS coordinates
+- **Orange circles** (`~HH`): Inferred positions (no GPS but deducible from contacts)
+- **Red endpoint**: Target contact with known GPS
+- **Magenta endpoint**: Target with guessed position
+
+A bottom panel shows each hop pair with SNR quality icons and total path distance. When multiple observed paths are available, a **Single / Combined** toggle appears at the top of the map. In Combined view, all paths are overlaid; shared segments are highlighted with a white halo and a path count badge appears on shared nodes.
+
+The bottom panel also provides **packet animation controls**:
+- **Animation toggle** (on/off)
+- **Step back / Play / Step forward / Replay** buttons
+- **Follow packet lock** — keeps the map camera centered on the moving packet dot
+- **Speed selector** (0.5×, 1×, 2×, 4×)
+- A live **"Hop x of y · from → to"** label that tracks the active segment
+
+### How It Works
+Sends a trace request frame over the mesh. The repeater network traces the path hop-by-hop and returns per-hop SNR data. For hops without GPS, positions are inferred by averaging GPS coordinates of contacts sharing that last-hop byte.
+
+---
+
+## Line-of-Sight (LOS) Analysis
+
+### How to Access
+From the main map, tap the terrain/antenna icon.
+
+### What the User Sees
+A full-screen map with a draggable bottom sheet containing:
+- **Elevation profile chart**: Terrain fill (green), LOS beam line (white), radio horizon line (yellow); obstruction points are marked as clickable dots on the chart
+- **Status summary**: Clear (green), Marginal (amber, within 5 m of obstruction), or Blocked (red) with distance and clearance/obstruction amount
+- **Options section** (collapsible): Node toggles, endpoint dropdowns, antenna height sliders (0–400 ft), Run LOS button
+
+### Key Interactions
+- **Long-press the map** to add custom endpoints (pushpin markers, renameable/deleteable)
+- **Tap a marker** to select it as Point A or B; LOS runs automatically when both are set
+- **Antenna heights** are adjustable for both endpoints
+- **Map line** between endpoints is colored green (clear), amber (marginal), or red (blocked)
+- Terrain elevation is fetched from the Open-Meteo API (21, 41, or 81 sample points depending on link distance, cached 24 hours)
+- K-factor is adjusted per radio frequency from a baseline of 4/3 at 915 MHz
+
+---
+
+## Offline Map Cache
+
+### How to Access
+Settings → App Settings → Map Display → Offline Map Cache
+
+### What the User Sees
+- Map with a blue polygon overlay showing previously selected cache bounds
+- Bounding box coordinates card
+- **Cache Area** controls: "Use Current View" and Clear buttons
+- **Zoom Range** range slider (3–18, dual-handle for min and max) with estimated tile count
+- **Download progress** bar (when downloading)
+- **Download Tiles** and **Clear Cache** buttons
+
+### Key Interactions
+1. Pan/zoom the map to the desired area
+2. Tap "Use Current View" to capture the viewport as cache bounds
+3. Adjust the zoom range slider
+4. Tap "Download Tiles" (confirmation dialog shows estimated count)
+5. Tiles are downloaded with up to 8 concurrent connections
+6. Once cached, tiles are served from disk without internet (365-day stale period)
+
+---
+
+## GPX Export
+
+### How to Access
+Settings → Export section
+
+### What It Does
+Exports contacts with GPS coordinates to a `.gpx` file via the OS share sheet. Three export options:
+- **Export Repeaters**: Repeater and Room contacts with locations
+- **Export Contacts**: Chat contacts with locations
+- **Export All**: All contacts with locations
+
+Each waypoint includes: name, lat/lon, type label, and public key hex.
+
+---
+
+## Location Data Sources
+
+The phone's own GPS is **never used**. All location data comes from the mesh:
+
+1. **Device self-location**: Read from firmware device-info response. Set manually in Settings → Location, or updated automatically if the device has a GPS module.
+2. **Remote node locations**: Extracted from advertisement packets received over the mesh. Encoded as integer lat/lon × 1,000,000.
@@ -0,0 +1,72 @@
+# Navigation
+
+## App Flow
+
+The app follows this general flow:
+
+```
+Launch → Scanner Screen → [Connect via BLE/USB/TCP] → Channels Screen
+```
+
+After connecting, the three main screens (Contacts, Channels, Map) are accessible via a persistent bottom navigation bar called the **QuickSwitchBar**.
+
+## Quick Switch Bar
+
+The QuickSwitchBar is a Material 3 `NavigationBar` with a frosted-glass visual treatment (blur backdrop, transparent theme, rounded corners). It appears at the bottom of all three main screens.
+
+| Index | Icon | Label | Screen |
+|---|---|---|---|
+| 0 | People | Contacts | ContactsScreen |
+| 1 | Tag | Channels | ChannelsScreen |
+| 2 | Map | Map | MapScreen |
+
+Tapping a tab replaces the current screen with a subtle fade + slight horizontal nudge transition (220ms forward, 200ms reverse). The back button is suppressed on all three main screens — navigation between them is flat, not stacked. All icons use outline variants (`people_outline`, `tag`, `map_outlined`) following Material 3 conventions.
+
+## Disconnection
+
+- The disconnect button (available in the overflow menu of each main screen) shows a confirmation dialog before disconnecting
+- If the device disconnects unexpectedly, the app automatically navigates back to the Scanner screen (fires after the current frame completes via a post-frame callback)
+- This auto-navigation behavior (`DisconnectNavigationMixin`) is shared across all main screens
+
+## Theme and Locale
+
+- **Theme mode** is user-configurable in App Settings (System / Light / Dark) — not locked to system
+- **Language** can be overridden to one of 18 supported languages, or follow the system locale
+- On web, if a non-Chromium browser is detected, the app shows a `ChromeRequiredScreen` instead of the Scanner (Web Bluetooth requires Chromium)
+
+## Full Navigation Graph
+
+```
+ScannerScreen (root, always on stack)
+  ├─ [BLE connect] → push → ChannelsScreen
+  ├─ [TCP icon button] → push → TcpScreen
+  │     └─ [TCP connected] → pushReplacement → ChannelsScreen
+  └─ [USB icon button] → push → UsbScreen
+        └─ [USB connected] → pushReplacement → ChannelsScreen
+
+ContactsScreen (selected=0)
+  ├─ [quick-switch 1] → pushReplacement → ChannelsScreen
+  ├─ [quick-switch 2] → pushReplacement → MapScreen
+  ├─ [tap contact] → push → ChatScreen
+  ├─ [overflow > Settings] → push → SettingsScreen
+  └─ [overflow > Discovered] → push → DiscoveryScreen
+
+ChannelsScreen (selected=1)
+  ├─ [quick-switch 0] → pushReplacement → ContactsScreen
+  ├─ [quick-switch 2] → pushReplacement → MapScreen
+  ├─ [tap channel] → push → ChannelChatScreen
+  └─ [overflow > Settings] → push → SettingsScreen
+
+MapScreen (selected=2)
+  ├─ [quick-switch 0] → pushReplacement → ContactsScreen
+  ├─ [quick-switch 1] → pushReplacement → ChannelsScreen
+  ├─ [radar menu item] → enters in-map path trace mode (push → PathTraceMapScreen after path is built)
+  ├─ [terrain menu item] → push → LineOfSightMapScreen
+  └─ [long-press] → share marker sheet
+
+Settings (push from any main screen)
+  └─ [App Settings] → push → AppSettingsScreen
+        └─ [Offline Map Cache] → push → MapCacheScreen
+```
+
+Any disconnection from any screen triggers `popUntil(route.isFirst)`, returning to the Scanner.
@@ -0,0 +1,92 @@
+# Notifications
+
+## Overview
+
+MeshCore Open provides both **system notifications** (push-style OS alerts) and **in-app unread badges** to inform users of new activity.
+
+## Notification Types
+
+### 1. Direct Message Notifications
+- **Triggered when**: A new incoming message arrives from a Chat or Room contact
+- **Title**: Contact's name
+- **Body**: Message text (reactions show "Reacted [emoji]", GIFs show "Sent a GIF")
+- **Priority**: High
+- **Android channel**: `messages`
+
+### 2. Channel Message Notifications
+- **Triggered when**: A new message arrives on a non-muted channel
+- **Title**: Channel name (or "Channel N" if unnamed)
+- **Body**: `"<senderName>: <message text>"`
+- **Priority**: High
+- **Android channel**: `channel_messages`
+
+### 3. Advertisement Notifications
+- **Triggered when**: A new node is discovered on the mesh for the first time
+- **Title**: "New [type] discovered" (e.g., "New Chat discovered")
+- **Body**: Contact's name
+- **Priority**: Default
+- **Android channel**: `adverts`
+
+### 4. Background Service Notification (Android Only)
+- A persistent low-priority notification: "MeshCore running — Keeping BLE connected"
+- Required by Android for foreground services to keep BLE alive in the background
+- Tap to re-launch the app
+- **Does not auto-start on reboot** — the user must re-open the app manually after a phone restart
+
+### Notification Tap Behavior
+
+Tapping a notification currently re-launches the app at the root route. It does **not** navigate directly to the relevant chat or channel.
+
+## In-App Unread Badges
+
+Red numeric badges appear throughout the UI:
+- **Contacts list**: Each contact row shows a red pill badge (e.g., "3") for unread messages
+- **Channels list**: Each channel row shows an unread badge
+- **Chat screen subtitle**: Shows unread count inline
+- Badges cap at "9999+" for display
+
+### How Unread Counts Work
+
+- Stored per contact (by public key) and per channel, **scoped to the connected device's identity** (first 10 hex characters of its public key). Switching between different radios gives each its own independent unread state
+- **Suppressed when viewing**: Opening a chat resets the count to 0 and cancels the OS notification
+- **Ignored for**: Outgoing messages, CLI messages, and repeater contacts
+- Debounced writes (500ms) to avoid excessive storage I/O during message bursts
+
+## Notification Settings
+
+Access via **App Settings → Notifications**:
+
+| Setting | Default | Description |
+|---|---|---|
+| Enable Notifications | On | Master toggle; requests OS permission when turned on |
+| Message Notifications | On | DM alerts (greyed out if master is off) |
+| Channel Message Notifications | On | Channel alerts (greyed out if master is off) |
+| Advertisement Notifications | On | New node alerts (greyed out if master is off) |
+
+### Per-Channel Muting
+
+Long-press a channel in the channels list → "Mute channel" / "Unmute channel". Muted channels do not generate OS notifications.
+
+There is no per-contact muting.
+
+## Rate Limiting
+
+The notification system prevents notification storms:
+- **Minimum interval**: 3 seconds between individual notifications
+- **Batch window**: If multiple notifications arrive within 5 seconds, they are combined into a single summary notification on a fourth Android channel (`batch_summary`). The title is "MeshCore Activity" and the body lists the grouped counts (e.g., "2 messages, 1 channel message, 3 new nodes"). Batch summaries are Android-only; queued notifications that overflow the batch window are silently dropped on other platforms
+
+## Notification Clearing
+
+- **Opening a contact chat**: Cancels the OS notification and resets unread count
+- **Opening a channel**: Cancels the channel notification and resets unread count
+- **Opening Contacts screen**: Cancels all advertisement notifications
+
+## Platform Support
+
+| Platform | Message Notifs | Badge | Background Service |
+|---|---|---|---|
+| Android | Yes | Via notification number | Yes (foreground service) |
+| iOS | Yes | Yes (app badge) | No |
+| macOS | Yes | Yes | No |
+| Windows | Yes | No | No |
+| Linux | Yes (if D-Bus available) | No | No |
@@ -0,0 +1,221 @@
+# Repeater Management
+
+## Overview
+
+Repeater Management provides tools for administering MeshCore repeater and room server nodes. It includes device status monitoring, CLI access, telemetry reading, neighbor discovery, and remote configuration.
+
+## How to Access
+
+From the Contacts screen:
+1. Long-press a **Repeater** or **Room** contact
+2. Select "Manage Repeater" or "Room Management"
+3. Enter the admin password in the login dialog
+4. Navigate to the Repeater Hub Screen
+
+### Login Dialog
+
+- Password field with show/hide toggle
+- "Save password" checkbox (persists for future logins). If a saved password exists, it is pre-filled and the checkbox is pre-checked, making login one-tap
+- Routing mode selector and "Manage Paths" link are available directly in the dialog (configure routing before login)
+- Auto-retries up to 5 times on timeout, showing progress ("Attempt 2 of 5"). A wrong password (explicit failure response) stops immediately — only timeouts trigger retries
+- If auto-clock-sync is enabled for this repeater (configured in Repeater Settings), a `clock sync` command is sent automatically on successful login
+
+---
+
+## Repeater Hub Screen
+
+The central management screen showing:
+
+- **Header card**: Repeater name, short public key, path label, GPS coordinates (if known)
+- **Battery chemistry selector**: NMC / LiFePO4 / LiPo (saved per repeater)
+- **Management tool cards** (full-width cards with chevron arrows, not a grid). Title dynamically shows "Repeater Management" or "Room Management" (admin) or "Repeater Guest" / "Room Guest" (guest) based on contact type and login result:
+
+| Card | Destination | Visibility |
+|---|---|---|
+| Status | Repeater Status Screen | All users |
+| Telemetry | Telemetry Screen | All users |
+| Neighbors | Neighbors Screen | All users |
+| CLI | Repeater CLI Screen | Admin only |
+| Settings | Repeater Settings Screen | Admin only |
+
+The battery chemistry selector and CLI/Settings cards are hidden from guest users.
+
+---
+
+## Repeater Status
+
+### What the User Sees
+
+Three information cards:
+
+**System Information**:
+- Battery percentage and voltage (e.g. "85% / 3.95V"), using the battery chemistry set in the hub screen
+- Clock at login time
+- Uptime (days/hours/minutes/seconds)
+- Queue length
+- Debug flags (error event count)
+
+**Radio Statistics**:
+- Last RSSI and SNR
+- Noise floor
+- TX airtime and RX airtime
+
+**Packet Statistics**:
+- Packets sent and received, each broken down by flood vs. direct
+- Duplicates, broken down by flood vs. direct
+- Channel utilization (% of uptime used by TX + RX)
+
+### Key Interactions
+- Auto-queries the repeater on open; shows a loading spinner until data arrives
+- On timeout: red snackbar error. On success: data appears in-place (no extra snackbar)
+- Pull-to-refresh or refresh button in the app bar to re-query
+- Routing mode popup and path management dialog in app bar (these controls appear on **all** management sub-screens, not just Status)
+- Accepts both binary `RESP_CODE_STATUS_RESPONSE` frames and legacy JSON text responses
+
+---
+
+## Repeater CLI
+
+A terminal-style interface for sending commands directly to the repeater.
+
+### What the User Sees
+
+- **Quick-command bar** (horizontal scroll): Shortcut buttons for 9 common commands (advert, get name, get radio, get tx, discover.neighbors, neighbors, ver, clock, clock sync)
+- **Command history list**: Sent commands in primary color, responses in secondary color
+- **Input bar**: Up/down history arrows, monospace text field with `> ` prefix, send button
+
+### Key Interactions
+
+- Type a command and press send (or Enter on desktop)
+- Up/down arrows navigate through command history
+- Quick-command buttons populate and send common commands
+- Overflow menu (three-dot icon): "Debug next command" option shows raw frame debug info for the next typed command (shows error snackbar if input field is empty)
+- Help icon: Opens a scrollable reference of all known CLI commands. Tapping any command populates the input field immediately
+- Clear icon: Wipes the command/response history
+- Failed/timed-out commands are automatically retried once
+
+### Available CLI Commands
+
+The in-app help reference (help icon) documents all known commands. Categories:
+
+**General**: `advert`, `advert.zerohop`, `reboot`, `clock`, `clock sync`, `password`, `ver`, `clear stats`, `erase`, `poweroff`, `shutdown`, `clkreboot`, `start ota`, `time`, `board`, `discover.neighbors`, `powersaving`, `stats-packets`, `stats-radio`, `stats-core`
+
+**Get**: `get name`, `get role`, `get public.key`, `get prv.key`, `get repeat`, `get tx`, `get freq`, `get radio`, `get radio.rxgain`, `get af`, `get dutycycle`, `get int.thresh`, `get agc.reset.interval`, `get multi.acks`, `get allow.read.only`, `get advert.interval`, `get flood.advert.interval`, `get guest.password`, `get lat`, `get lon`, `get rxdelay`, `get txdelay`, `get direct.txdelay`, `get flood.max`, `get owner.info`, `get path.hash.mode`, `get loop.detect`, `get acl`, `get bridge.*`, `get adc.multiplier`, `get bootloader.ver`
+
+**Set**: `set name`, `set af`, `set tx`, `set repeat`, `set allow.read.only`, `set flood.max`, `set int.thresh`, `set agc.reset.interval`, `set multi.acks`, `set advert.interval`, `set flood.advert.interval`, `set guest.password`, `set lat`, `set lon`, `set freq`, `set radio`, `set rxdelay`, `set txdelay`, `set direct.txdelay`, `set radio.rxgain`, `set dutycycle`, `set loop.detect`, `set path.hash.mode`, `set owner.info`, `set prv.key`, `set bridge.*`, `set adc.multiplier`, `tempradio`, `setperm`
+
+**Bridge**: `get bridge.type`
+
+**Logging**: `log start`, `log stop`, `log erase`
+
+**Neighbors**: `neighbors`, `neighbor.remove`
+
+**Power Management**: `get pwrmgt.support`, `get pwrmgt.source`, `get pwrmgt.bootreason`, `get pwrmgt.bootmv`
+
+**Sensors**: `sensor get {key}`, `sensor set {key} {value}`, `sensor list [start]`
+
+**GPS Management**: `gps`, `gps {on|off}`, `gps sync`, `gps setloc`, `gps advert`, `gps advert {none|share|prefs}`
+
+**Region Management**: `region`, `region load`, `region get`, `region put`, `region remove`, `region allowf`, `region denyf`, `region home`, `region save`, `region default`, `region list allowed`, `region list denied`
+
+---
+
+## Telemetry
+
+### What the User Sees
+
+A list of Cayenne LPP sensor channel cards:
+
+- **Channel 1** (special): Battery voltage (shown as percentage or raw mV) and MCU temperature
+- **Other channels**: Raw sensor values with appropriate labels
+
+Shows "No data" until a response arrives from the repeater.
+
+### Key Interactions
+- Auto-queries on open
+- Pull-to-refresh
+- Temperature respects metric/imperial setting
+- Battery readings are stored for the repeater's battery snapshot
+
+---
+
+## Neighbors
+
+### What the User Sees
+
+A card titled "Repeater's Neighbors - N" listing each neighbor as:
+- Repeater name (or hex key prefix if unknown)
+- Time since last heard
+- SNR quality icon with color coding and label
+
+### Key Interactions
+- Auto-queries up to 15 neighbors on open
+- Matches public key prefixes against known contacts to show names
+- Pull-to-refresh
+
+---
+
+## Repeater Settings
+
+### What the User Sees
+
+Nine configuration cards, each with its own per-field refresh button(s):
+
+**1. Basic Settings**
+- Name field
+- Admin password field (write-only; always sent when non-empty)
+- Guest password field (write-only; always sent when non-empty)
+
+**2. Radio Settings**
+- Frequency (MHz)
+- TX Power (dBm) — has its own independent refresh button
+- Bandwidth dropdown (kHz)
+- Spreading Factor (SF5–SF12)
+- Coding Rate (4/5–4/8)
+- RX Gain boost toggle
+
+**3. Location Settings**
+- Latitude and longitude fields, each with an independent refresh button
+
+**4. Features**
+- Packet forwarding toggle (`set repeat`)
+- Guest access toggle (`set allow.read.only`)
+- Multi-ACKs toggle (`set multi.acks`)
+- Auto clock sync after login toggle (local app setting only, not sent to repeater)
+
+**5. Network Health**
+- Loop detection dropdown (off / minimal / moderate / strict; `set loop.detect`)
+- Duty cycle slider (1–100%; `set dutycycle`)
+
+**6. Advertisement Settings**
+- Local advert interval slider (60–240 minutes) with enable/disable toggle
+- Flood advert interval slider (3–168 hours) with enable/disable toggle
+- Flood max hops slider (0–64; `set flood.max`)
+
+**7. Owner Info**
+- Multi-line text field for operator contact info (`set owner.info`); newlines sent as `|`
+
+**8. Actions** (one-tap, no save needed)
+- Send Advertisement (`advert`)
+- Send Zero-Hop Advertisement (`advert.zerohop`)
+- Clock Sync (`clock sync`)
+
+**9. Advanced** (collapsed by default)
+- Path hash mode dropdown (0–2; `set path.hash.mode`)
+- TX delay field (`set txdelay`)
+- Direct TX delay field (`set direct.txdelay`)
+- Interference threshold field (`set int.thresh`)
+- AGC reset interval slider (0–240s in multiples of 4; `set agc.reset.interval`)
+
+**Danger Zone** (red-styled card)
+- Reboot repeater (sends `reboot` with confirmation dialog)
+- Erase filesystem (serial-only; shows a confirmation dialog, then an informational snackbar — no command is sent over the air)
+
+### Key Interactions
+- **Settings are NOT auto-fetched on open**. Name is pre-filled from cached contact data. Each section has its own refresh button to fetch live values from the repeater
+- TX Power, RX Gain, latitude, longitude, and advanced fields each have independent inline refresh buttons
+- Save button in app bar appears when any change is detected; failed commands keep those fields dirty for retry
+- Settings are sent sequentially with 200ms delays between commands; firmware responses are checked and partial failures are reported in a snackbar
+- Some changes (e.g. radio frequency) require a reboot; the firmware response triggers an orange "reboot needed" snackbar
+- Advertisement interval sliders reset to defaults when re-enabled (local: 60 min, flood: 3 hours)
+- **Erase Filesystem** does NOT send any command over the air — tapping it only shows a snackbar explaining the operation requires physical serial access
@@ -0,0 +1,126 @@
+# Scanner & Connection
+
+## BLE Scanner (Home Screen)
+
+The BLE Scanner is the app's home screen, displayed immediately on launch.
+
+### How to Access
+
+- Opens automatically when the app starts
+- Returns here when disconnecting from any device
+- Accessible by navigating back from a connected session
+
+### What the User Sees
+
+**App Bar**: Centered title "Scanner".
+
+**Bluetooth-Off Warning Banner** (conditional): Appears when the Bluetooth adapter is off, showing a `bluetooth_disabled` icon, a warning message, and on Android, an "Enable Bluetooth" button.
+
+**Status Bar**: A full-width colored strip reflecting the current connection state:
+
+| State | Text | Color |
+|---|---|---|
+| Disconnected | "Not connected" | Grey |
+| Scanning | "Scanning..." | Blue |
+| Connecting | "Connecting..." | Orange |
+| Connected | "Connected to \<device name\>" | Green |
+| Disconnecting | "Disconnecting..." | Orange |
+
+**Device List**: When no devices are found, shows a large Bluetooth icon with a prompt. The prompt text is dynamic: "Searching for devices..." while actively scanning, or "Tap Scan to search" when idle. When devices are found, shows a scrollable list of `DeviceTile` widgets.
+
+**App Bar Actions**: Icon buttons in the top-right corner of the app bar:
+- **USB** icon button - Opens USB connection screen (Android, Windows, Linux, macOS, Chrome web only)
+- **TCP/IP** icon button - Opens TCP connection screen (all non-web platforms)
+
+**Bottom FAB**: A single floating action button:
+- **BLE Scan** button - Toggles BLE scanning on/off; shows a spinner when scanning. **Disabled** (greyed out, not tappable) when Bluetooth is off
+
+### Device Tile
+
+Each discovered device is displayed as a list tile showing:
+- **Signal strength icon** (color-coded by RSSI):
+  - Green: >= -60 dBm (excellent)
+  - Light green: -60 to -70 dBm (good)
+  - Amber: -70 to -80 dBm (fair)
+  - Orange: -80 to -90 dBm (weak)
+  - Red: < -90 dBm (poor)
+- **RSSI value** in dBm (e.g., "-72 dBm")
+- **Device name** (falls back to "Unknown Device")
+- **Device ID** (BLE MAC address on Android; a system-assigned UUID on iOS/macOS)
+- **Connect button** (the entire tile row is also tappable — both trigger connection)
+
+Note: The weak (-80 to -90 dBm) and poor (< -90 dBm) tiers share the same icon shape and are only differentiated by color (orange vs. red).
+
+### How Scanning Works
+
+- Filters for devices advertising the Nordic UART Service UUID (so community forks with non-standard names are still found). Known name prefixes used by stock firmware builds for reference: `MeshCore-`, `Whisper-`, `WisCore-`, `Seeed`, `Lilygo`, `HT-`, `LowMesh_MC_`, `NRF52`
+- Uses low-latency scan mode on Android
+- Scans for 10 seconds then auto-stops
+- On iOS/macOS, waits for BLE adapter initialization before starting
+- If Bluetooth is turned off during a scan, scanning stops immediately
+
+### Connecting to a Device
+
+Tap a device tile or its Connect button:
+1. The connector stops scanning and transitions to "connecting"
+2. Connects to the device with a 15-second timeout (6 seconds on Linux)
+3. Requests MTU 185 bytes for optimal throughput
+4. Discovers BLE services and locates the Nordic UART Service
+5. Subscribes to TX notifications for receiving data
+6. On success, automatically navigates to the Channels screen
+7. On failure, shows a red error snackbar
+
+---
+
+## USB Connection
+
+### How to Access
+
+From the Scanner screen, tap the **USB** icon button in the app bar.
+
+### What the User Sees
+
+- A colored status bar at the top (same color scheme as BLE scanner)
+- A list of detected USB serial ports, each showing:
+  - Friendly display name
+  - Raw port name (subtitle, only shown when it differs from the display name)
+  - Chevron trailing icon (the entire tile is tappable to connect)
+- Transport switcher buttons (outlined, not FABs) to switch to BLE or TCP (these use `pushReplacement`, so back navigation returns to Scanner, not between USB/TCP)
+
+### Key Interactions
+
+- On desktop (Windows, Linux, macOS): ports are polled every 2 seconds for hot-plug detection (polling pauses while connecting/connected)
+- On mobile: tap the "Scan" FAB to manually refresh
+- Tap a port tile to connect
+- On successful connection, navigates to Channels screen
+- On connection failure, the port list automatically refreshes
+- Platform-specific error messages for common USB failures (permission denied, device missing, device detached, device busy, driver missing, port invalid, timeout, and more)
+
+---
+
+## TCP Connection
+
+### How to Access
+
+From the Scanner screen, tap the **TCP/IP** icon button in the app bar.
+
+### What the User Sees
+
+- A colored status bar at the top
+- **Host address** text field
+- **Port number** text field
+- **Connect** button
+- Transport switcher buttons (outlined, not FABs) to switch to USB or BLE
+
+### Key Interactions
+
+- Last-used host and port are pre-populated from saved settings
+- Tap Connect to validate inputs and connect
+  - Host must not be empty
+  - Port must be a number between 1 and 65535
+  - Validation errors are shown as red snackbars
+- The Connect button shows a spinner and "Connecting..." label while in progress
+- The status bar shows the specific host:port being connected to (e.g., "Connecting to 192.168.1.1:5000")
+- On success, navigates to Channels screen and saves the host/port to settings
+- On connection, the status bar shows the active TCP endpoint (e.g., "Connected to 192.168.1.1:5000")
+- Error messages for timeout, unsupported platform, and connection failures
@@ -0,0 +1,197 @@
+# Settings
+
+## How to Access
+
+- From the Device Screen: tap the tune/sliders icon in the app bar
+- From Contacts or Channels: overflow menu (three-dot) → Settings
+
+Settings are only accessible while a device is connected.
+
+## Settings Screen Layout
+
+The settings screen is a scrollable list of cards:
+
+1. [Device Info](#device-info)
+2. [Node Settings](#node-settings)
+3. [Location](#location)
+4. [App Settings](#app-settings) (link to sub-screen)
+5. [Actions](#actions)
+6. [Export](#export)
+7. [Debug](#debug)
+8. [About](#about)
+
+---
+
+## Device Info
+
+A collapsible card showing read-only device information. **Collapsed by default** — tap the header to expand with an animated chevron indicator:
+
+| Field | Description |
+|---|---|
+| Name | Connected device's display name |
+| ID | Device identifier |
+| Status | Connected / Disconnected |
+| Battery | Percentage or voltage (tap to toggle) |
+| Node Name | The node's mesh identity name |
+| Public Key | First 16 hex characters + "..." |
+| Contacts Count | Number of known contacts |
+| Channel Count | Number of configured channels |
+
+Battery shows an alert icon and orange text when at 15% or below. The toggle only works when millivolt data is available from the firmware.
+
+---
+
+## Node Settings
+
+These settings are sent directly to the connected device firmware.
+
+### Node Name
+- Opens a dialog with a text field (max 31 characters)
+- Sends the new name to the device
+- Confirmed via snackbar
+
+### Radio Settings
+Opens a dialog pre-populated with the device's current radio settings. Contains:
+- **Preset dropdown**: Regional presets — selecting a preset immediately fills all fields below. Includes presets for Australia, Australia (Narrow), Australia SA WA QLD, Czech Republic, EU 433MHz, EU/UK (Long Range), EU/UK (Medium Range), EU/UK (Narrow), New Zealand, New Zealand (Narrow), Portugal 433, Portugal 869, numerous Russia city presets, Switzerland, USA Arizona, USA/Canada, and Vietnam
+- **Frequency** (MHz): Free text, validated 300–2500 MHz
+- **Bandwidth**: Dropdown (7.8 / 10.4 / 15.6 / 20.8 / 31.25 / 41.7 / 62.5 / 125 / 250 / 500 kHz)
+- **Spreading Factor**: SF5–SF12
+- **Coding Rate**: 4/5, 4/6, 4/7, 4/8
+- **TX Power** (dBm): Validated 0 to device max (typically 22 dBm)
+- **Client Repeat** toggle: Only shown on firmware v9+; requires frequency to be exactly 433.000, 869.000, or 918.000 MHz (the Off-Grid presets). Save is blocked with a warning if enabled on other frequencies
+
+### Companion Radio Stats
+Opens the RF statistics screen (RSSI, SNR, packet counts) for the paired radio. Only enabled when connected to a device that supports companion radio stats.
+
+---
+
+## Location
+
+### Location
+Opens a dialog pre-populated with the device's current coordinates (if known):
+- Latitude and longitude fields (decimal, 6 decimal places). If only one field is provided, the other uses the device's current value
+- If GPS-capable hardware (detected via `gps` custom variable):
+  - GPS Update Interval (seconds, 60–86399, default 900 = 15 minutes). Validated and sent separately before lat/lon
+  - Enable GPS toggle (takes effect immediately, not deferred to Save)
+- Validation: lat ±90, lon ±180
+
+### Contact Settings
+Five toggles controlling which node types are auto-added when heard:
+- Auto-add Chat Users
+- Auto-add Repeaters
+- Auto-add Room Servers
+- Auto-add Sensors
+- Overwrite Oldest (when contact list is full)
+
+### Privacy
+Opens a dialog with controls for how the node shares telemetry and location data:
+- **Advert Location**: Toggle whether the node broadcasts its location in advertisements
+- **Multi-Ack**: Toggle multi-ack delivery confirmations
+- **Telemetry Base Mode**: Deny All / Allow by Contact / Allow All
+- **Telemetry Location Mode**: Deny All / Allow by Contact / Allow All
+- **Telemetry Environment Mode**: Deny All / Allow by Contact / Allow All
+
+Settings take effect when saved. A snackbar confirms the update.
+
+---
+
+## App Settings
+
+A dedicated sub-screen for app-level preferences (nothing here is sent to the device). All settings persist locally via SharedPreferences.
+
+### Appearance
+- **Theme**: System / Light / Dark
+- **Language**: System default or one of 18 languages (English, French, Spanish, German, Polish, Slovenian, Portuguese, Italian, Chinese, Swedish, Dutch, Slovak, Bulgarian, Russian, Ukrainian, Hungarian, Japanese, Korean)
+
+### Notifications
+- **Master enable/disable**: Requests OS permission when enabling
+- **Message notifications**: New direct message alerts
+- **Channel message notifications**: New channel message alerts
+- **Advertisement notifications**: New node discovery alerts
+
+### Messaging
+- **Clear Path on Max Retry**: Erases the stored routing path after all retries fail
+- **Jump to Oldest Unread**: When opening a chat, scrolls to the oldest unread message instead of the newest
+- **Auto Route Rotation**: Enables weighted routing algorithm. When enabled, expands to show five slider sub-settings (hidden when off):
+  - Max Route Weight (1–10, default 5, integer steps)
+  - Initial Route Weight (0.5–5.0, default 3.0)
+  - Success Increment (0.1–2.0, default 0.5, 0.1 steps)
+  - Failure Decrement (0.1–2.0, default 0.2, 0.1 steps)
+  - Max Message Retries (2–10, default 5)
+- **Enable Message Tracing**: Shows path trace overlays and extra metadata on messages
+
+### Battery
+- **Battery Chemistry**: NMC / LiFePO4 / LiPo (per device, used to calibrate percentage from voltage)
+
+### Map Display
+- **Show Repeaters**: Toggle repeater markers on map
+- **Show Chat Nodes**: Toggle chat node markers
+- **Show Other Nodes**: Toggle room/sensor markers
+- **Time Filter**: All time / Last 1h / Last 6h / Last 24h / Last week
+- **Units**: Metric / Imperial
+- **Offline Map Cache**: Navigate to tile download screen
+
+### Translation
+Not shown on web. Controls on-device message translation powered by a locally-downloaded ML model:
+- **Enable Translation**: Translates incoming messages into the selected target language
+- **Translate Composer**: Translates outgoing messages from the target language back before sending
+- **Target Language**: Language to translate into (searchable list; defaults to the app language)
+- **Downloaded Model**: Dropdown to select among already-downloaded translation models
+- **Preset Model**: Download a curated preset model with one tap
+- **Custom Model URL**: Enter a URL to download a custom GGUF-format model; shows download progress and a cancel button
+
+### Cyrillic-to-Latin (Cyr2Lat)
+Controls character substitution profiles used to render Cyrillic text in Latin characters. A dropdown selects the active profile; Add, Edit, and Delete buttons manage the profile list (the last remaining profile cannot be deleted). Each profile stores a JSON character map.
+
+### Debug
+- **App Debug Logging**: Enable the in-app debug log
+
+---
+
+## Actions
+
+One-tap device operations:
+
+| Action | Description |
+|---|---|
+| Sync Time | Sends current Unix timestamp to the device |
+| Refresh Contacts | Re-requests the full contact list |
+| Reboot Device | Confirmation dialog → reboots the device (shown in warning color) |
+| Delete All Paths | Confirmation dialog → clears all stored routing paths (shown in alert color) |
+
+---
+
+## Export
+
+Three GPX export options (not available on web):
+
+| Option | Exports |
+|---|---|
+| Export Repeaters | Repeaters and Rooms with GPS coordinates |
+| Export Contacts | Chat contacts with GPS coordinates |
+| Export All | All contacts with GPS coordinates |
+
+Each creates a `.gpx` file and opens the OS share sheet. Feedback via snackbar for four outcomes: success, no contacts with coordinates, feature not available (web), or error.
+
+---
+
+## Debug
+
+Two log viewers accessible via list tiles:
+
+### BLE Debug Log
+Two views (togglable via segmented button):
+- **Frames view**: Direction icon, description, hex preview, timestamp per frame. Long-press to copy hex.
+- **Raw Log RX view**: Decoded LoRa packets with route type, payload type, path, and summary.
+- Copy-all and Clear buttons in the app bar.
+
+### App Debug Log
+Structured log entries (Info / Warning / Error), with tag, message, and timestamp.
+- Must be enabled first in App Settings → Debug
+- Copy-all and Clear buttons
+
+---
+
+## About
+
+Shows the standard Flutter about dialog with app name, version, and legal notice.
@@ -0,0 +1,61 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1770562336,
+        "narHash": "sha256-ub1gpAONMFsT/GU2hV6ZWJjur8rJ6kKxdm9IlCT0j84=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "d6c71932130818840fc8fe9509cf50be8c64634f",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
@@ -0,0 +1,86 @@
+{
+  description = "MeshCore Flutter Application";
+
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = { self, nixpkgs, flake-utils }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        pkgs = nixpkgs.legacyPackages.${system};
+      in
+      {
+        devShells.default = pkgs.mkShell {
+          buildInputs = with pkgs; [
+            # Flutter and Dart
+            flutter
+            dart
+
+            # Java (required for Android development)
+            jdk17
+
+            # Android development tools
+            android-tools
+            gradle
+
+            # For the shell hook to set up the environment for Flutter development
+            gtk3
+            glib
+            sysprof
+            libclang
+            cmake
+            ninja
+            pkg-config
+            libdatrie
+
+            # Additional tools for installing Android SDK if not present
+            curl
+            unzip
+          ];
+
+          shellHook = ''
+            echo "MeshCore Flutter Development Environment"
+            export PKG_CONFIG_PATH="${pkgs.gtk3}/lib/pkgconfig:${pkgs.glib}/lib/pkgconfig:${pkgs.sysprof}/lib/pkgconfig:$PKG_CONFIG_PATH"
+            export LD_LIBRARY_PATH="${pkgs.lib.makeLibraryPath [pkgs.gtk3 pkgs.glib pkgs.sysprof pkgs.libdatrie]}:$LD_LIBRARY_PATH"
+            export CMAKE_INSTALL_PREFIX="$PWD/build/bundle"
+            
+            # Setup Android SDK in home directory (standard location)
+            export ANDROID_HOME="$HOME/Android/Sdk"
+            export ANDROID_SDK_ROOT="$ANDROID_HOME"
+            export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools/bin:$PATH"
+            
+            echo "Android SDK: $ANDROID_HOME"
+            echo ""
+            
+            # Check if Android SDK exists and offer to download if not
+            if [ ! -d "$ANDROID_HOME" ]; then
+              echo "WARNING: Android SDK not found at $ANDROID_HOME"
+              echo ""
+              echo "To download and set up the Android SDK, run this command:"
+              echo ""
+              cat << 'EOF'
+mkdir -p ~/Android/Sdk && cd ~/Android/Sdk && \
+curl -o cmdline-tools.zip ${if pkgs.stdenv.isDarwin then "https://dl.google.com/android/repository/commandlinetools-mac-10406996_latest.zip" else "https://dl.google.com/android/repository/commandlinetools-linux-10406996_latest.zip"} && \
+unzip -q cmdline-tools.zip && \
+mkdir -p cmdline-tools/latest && \
+mv cmdline-tools/* cmdline-tools/latest/ 2>/dev/null || echo "Warning: failed to move Android cmdline-tools into 'latest' directory; please check your SDK layout." >&2 && \
+rm cmdline-tools.zip && \
+cd cmdline-tools/latest/bin && \
+yes | ./sdkmanager --sdk_root=~/Android/Sdk 'platform-tools' && \
+echo "Android SDK setup complete!"
+EOF
+              echo ""
+              echo "Then run 'flutter doctor' again to verify."
+              echo ""
+            else
+              echo "Android SDK found at $ANDROID_HOME"
+            fi
+            
+            echo "To check that everything is set up correctly, run 'flutter doctor' and ensure there are no issues."
+          '';
+        };
+      }
+    );
+}
@@ -20,7 +20,5 @@
  <string>????</string>
  <key>CFBundleVersion</key>
  <string>1.0</string>
-  <key>MinimumOSVersion</key>
-  <string>13.0</string>
 </dict>
 </plist>
@@ -1,4 +1,4 @@
-platform :ios, '15.5'
+platform :ios, '16.4'

 ENV['COCOAPODS_DISABLE_STATS'] = 'true'

@@ -32,5 +32,8 @@ end
 post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
+    target.build_configurations.each do |config|
+      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '16.4'
+    end
  end
 end
@@ -7,57 +7,13 @@ PODS:
    - Flutter
  - flutter_local_notifications (0.0.1):
    - Flutter
-  - GoogleDataTransport (10.1.0):
-    - nanopb (~> 3.30910.0)
-    - PromisesObjC (~> 2.4)
-  - GoogleMLKit/BarcodeScanning (7.0.0):
-    - GoogleMLKit/MLKitCore
-    - MLKitBarcodeScanning (~> 6.0.0)
-  - GoogleMLKit/MLKitCore (7.0.0):
-    - MLKitCommon (~> 12.0.0)
-  - GoogleToolboxForMac/Defines (4.2.1)
-  - GoogleToolboxForMac/Logger (4.2.1):
-    - GoogleToolboxForMac/Defines (= 4.2.1)
-  - "GoogleToolboxForMac/NSData+zlib (4.2.1)":
-    - GoogleToolboxForMac/Defines (= 4.2.1)
-  - GoogleUtilities/Environment (8.1.0):
-    - GoogleUtilities/Privacy
-  - GoogleUtilities/Logger (8.1.0):
-    - GoogleUtilities/Environment
-    - GoogleUtilities/Privacy
-  - GoogleUtilities/Privacy (8.1.0)
-  - GoogleUtilities/UserDefaults (8.1.0):
-    - GoogleUtilities/Logger
-    - GoogleUtilities/Privacy
-  - GTMSessionFetcher/Core (3.5.0)
-  - MLImage (1.0.0-beta6)
-  - MLKitBarcodeScanning (6.0.0):
-    - MLKitCommon (~> 12.0)
-    - MLKitVision (~> 8.0)
-  - MLKitCommon (12.0.0):
-    - GoogleDataTransport (~> 10.0)
-    - GoogleToolboxForMac/Logger (< 5.0, >= 4.2.1)
-    - "GoogleToolboxForMac/NSData+zlib (< 5.0, >= 4.2.1)"
-    - GoogleUtilities/Logger (~> 8.0)
-    - GoogleUtilities/UserDefaults (~> 8.0)
-    - GTMSessionFetcher/Core (< 4.0, >= 3.3.2)
-  - MLKitVision (8.0.0):
-    - GoogleToolboxForMac/Logger (< 5.0, >= 4.2.1)
-    - "GoogleToolboxForMac/NSData+zlib (< 5.0, >= 4.2.1)"
-    - GTMSessionFetcher/Core (< 4.0, >= 3.3.2)
-    - MLImage (= 1.0.0-beta6)
-    - MLKitCommon (~> 12.0)
-  - mobile_scanner (6.0.2):
+  - mobile_scanner (7.0.0):
    - Flutter
-    - GoogleMLKit/BarcodeScanning (~> 7.0.0)
-  - nanopb (3.30910.0):
-    - nanopb/decode (= 3.30910.0)
-    - nanopb/encode (= 3.30910.0)
-  - nanopb/decode (3.30910.0)
-  - nanopb/encode (3.30910.0)
+    - FlutterMacOS
  - package_info_plus (0.4.5):
    - Flutter
-  - PromisesObjC (2.4.0)
+  - share_plus (0.0.1):
+    - Flutter
  - shared_preferences_foundation (0.0.1):
    - Flutter
    - FlutterMacOS
@@ -66,34 +22,18 @@ PODS:
    - FlutterMacOS
  - url_launcher_ios (0.0.1):
    - Flutter
-  - wakelock_plus (0.0.1):
-    - Flutter

 DEPENDENCIES:
  - Flutter (from `Flutter`)
  - flutter_blue_plus_darwin (from `.symlinks/plugins/flutter_blue_plus_darwin/darwin`)
  - flutter_foreground_task (from `.symlinks/plugins/flutter_foreground_task/ios`)
  - flutter_local_notifications (from `.symlinks/plugins/flutter_local_notifications/ios`)
-  - mobile_scanner (from `.symlinks/plugins/mobile_scanner/ios`)
+  - mobile_scanner (from `.symlinks/plugins/mobile_scanner/darwin`)
  - package_info_plus (from `.symlinks/plugins/package_info_plus/ios`)
+  - share_plus (from `.symlinks/plugins/share_plus/ios`)
  - shared_preferences_foundation (from `.symlinks/plugins/shared_preferences_foundation/darwin`)
  - sqflite_darwin (from `.symlinks/plugins/sqflite_darwin/darwin`)
  - url_launcher_ios (from `.symlinks/plugins/url_launcher_ios/ios`)
-  - wakelock_plus (from `.symlinks/plugins/wakelock_plus/ios`)
-
-SPEC REPOS:
-  trunk:
-    - GoogleDataTransport
-    - GoogleMLKit
-    - GoogleToolboxForMac
-    - GoogleUtilities
-    - GTMSessionFetcher
-    - MLImage
-    - MLKitBarcodeScanning
-    - MLKitCommon
-    - MLKitVision
-    - nanopb
-    - PromisesObjC

 EXTERNAL SOURCES:
  Flutter:
@@ -105,41 +45,30 @@ EXTERNAL SOURCES:
  flutter_local_notifications:
    :path: ".symlinks/plugins/flutter_local_notifications/ios"
  mobile_scanner:
-    :path: ".symlinks/plugins/mobile_scanner/ios"
+    :path: ".symlinks/plugins/mobile_scanner/darwin"
  package_info_plus:
    :path: ".symlinks/plugins/package_info_plus/ios"
+  share_plus:
+    :path: ".symlinks/plugins/share_plus/ios"
  shared_preferences_foundation:
    :path: ".symlinks/plugins/shared_preferences_foundation/darwin"
  sqflite_darwin:
    :path: ".symlinks/plugins/sqflite_darwin/darwin"
  url_launcher_ios:
    :path: ".symlinks/plugins/url_launcher_ios/ios"
-  wakelock_plus:
-    :path: ".symlinks/plugins/wakelock_plus/ios"

 SPEC CHECKSUMS:
  Flutter: cabc95a1d2626b1b06e7179b784ebcf0c0cde467
  flutter_blue_plus_darwin: 20a08bfeaa0f7804d524858d3d8744bcc1b6dbc3
  flutter_foreground_task: a159d2c2173b33699ddb3e6c2a067045d7cebb89
-  flutter_local_notifications: 395056b3175ba4f08480a7c5de30cd36d69827e4
-  GoogleDataTransport: aae35b7ea0c09004c3797d53c8c41f66f219d6a7
-  GoogleMLKit: eff9e23ec1d90ea4157a1ee2e32a4f610c5b3318
-  GoogleToolboxForMac: d1a2cbf009c453f4d6ded37c105e2f67a32206d8
-  GoogleUtilities: 00c88b9a86066ef77f0da2fab05f65d7768ed8e1
-  GTMSessionFetcher: 5aea5ba6bd522a239e236100971f10cb71b96ab6
-  MLImage: 0ad1c5f50edd027672d8b26b0fee78a8b4a0fc56
-  MLKitBarcodeScanning: 0a3064da0a7f49ac24ceb3cb46a5bc67496facd2
-  MLKitCommon: 07c2c33ae5640e5380beaaa6e4b9c249a205542d
-  MLKitVision: 45e79d68845a2de77e2dd4d7f07947f0ed157b0e
-  mobile_scanner: af8f71879eaba2bbcb4d86c6a462c3c0e7f23036
-  nanopb: fad817b59e0457d11a5dfbde799381cd727c1275
+  flutter_local_notifications: a5a732f069baa862e728d839dd2ebb904737effb
+  mobile_scanner: 9157936403f5a0644ca3779a38ff8404c5434a93
  package_info_plus: af8e2ca6888548050f16fa2f1938db7b5a5df499
-  PromisesObjC: f5707f49cb48b9636751c5b2e7d227e43fba9f47
+  share_plus: 50da8cb520a8f0f65671c6c6a99b3617ed10a58a
  shared_preferences_foundation: 7036424c3d8ec98dfe75ff1667cb0cd531ec82bb
  sqflite_darwin: 20b2a3a3b70e43edae938624ce550a3cbf66a3d0
  url_launcher_ios: 7a95fa5b60cc718a708b8f2966718e93db0cef1b
-  wakelock_plus: e29112ab3ef0b318e58cfa5c32326458be66b556

-PODFILE CHECKSUM: 570da2a631486c6bd6496bed1e605e63e2471be5
+PODFILE CHECKSUM: e42b502c78c33aa1ed9d42eaea8960ce2139504b

 COCOAPODS: 1.16.2
@@ -179,6 +179,7 @@
 				97C146EC1CF9000F007C117D /* Resources */,
 				9705A1C41CF9048500538489 /* Embed Frameworks */,
 				3B06AD1E1E4923F5004D2608 /* Thin Binary */,
+				F0D7F2413C6E4B7A9B1C2D3E /* Fix Native Asset Minimum OS */,
 				B788CEDB957A87EE8AC593BB /* [CP] Copy Pods Resources */,
 			);
 			buildRules = (
@@ -299,6 +300,22 @@
 			shellScript = "\"${PODS_ROOT}/Target Support Files/Pods-Runner/Pods-Runner-resources.sh\"\n";
 			showEnvVarsInLog = 0;
 		};
+		F0D7F2413C6E4B7A9B1C2D3E /* Fix Native Asset Minimum OS */ = {
+			isa = PBXShellScriptBuildPhase;
+			alwaysOutOfDate = 1;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			inputPaths = (
+				"${TARGET_BUILD_DIR}/${FRAMEWORKS_FOLDER_PATH}",
+			);
+			name = "Fix Native Asset Minimum OS";
+			outputPaths = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+			shellPath = /bin/sh;
+			shellScript = "set -e\nFRAMEWORKS_DIR=\"${TARGET_BUILD_DIR}/${FRAMEWORKS_FOLDER_PATH}\"\nMIN_OS=\"${IPHONEOS_DEPLOYMENT_TARGET}\"\nif [ ! -d \"$FRAMEWORKS_DIR\" ] || [ -z \"$MIN_OS\" ]; then\n  exit 0\nfi\nfind \"$FRAMEWORKS_DIR\" -maxdepth 2 -name Info.plist | while read -r plist; do\n  bundle_id=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' \"$plist\" 2>/dev/null || true)\n  case \"$bundle_id\" in\n    io.flutter.flutter.native-assets.*)\n      /usr/libexec/PlistBuddy -c \"Set :MinimumOSVersion $MIN_OS\" \"$plist\" 2>/dev/null || \\\n      /usr/libexec/PlistBuddy -c \"Add :MinimumOSVersion string $MIN_OS\" \"$plist\"\n      ;;\n  esac\ndone\n";
+		};
 		DE3B2E091393835C0B38492E /* [CP] Check Pods Manifest.lock */ = {
 			isa = PBXShellScriptBuildPhase;
 			buildActionMask = 2147483647;
@@ -414,7 +431,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 13.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 16.4;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				SDKROOT = iphoneos;
 				SUPPORTED_PLATFORMS = iphoneos;
@@ -540,7 +557,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 13.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 16.4;
 				MTL_ENABLE_DEBUG_INFO = YES;
 				ONLY_ACTIVE_ARCH = YES;
 				SDKROOT = iphoneos;
@@ -591,7 +608,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 13.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 16.4;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				SDKROOT = iphoneos;
 				SUPPORTED_PLATFORMS = iphoneos;
@@ -2,12 +2,15 @@ import Flutter
 import UIKit

@main
-@objc class AppDelegate: FlutterAppDelegate {
+@objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
-    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
+
+  func didInitializeImplicitFlutterEngine(_ engineBridge: FlutterImplicitEngineBridge) {
+    GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
+  }
 }
@@ -2,6 +2,8 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
+	<key>CADisableMinimumFrameDurationOnPhone</key>
+	<true/>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>$(DEVELOPMENT_LANGUAGE)</string>
 	<key>CFBundleDisplayName</key>
@@ -22,8 +24,46 @@
 	<string>????</string>
 	<key>CFBundleVersion</key>
 	<string>$(FLUTTER_BUILD_NUMBER)</string>
+	<key>LSApplicationQueriesSchemes</key>
+	<array>
+		<string>http</string>
+		<string>https</string>
+	</array>
 	<key>LSRequiresIPhoneOS</key>
 	<true/>
+	<key>NSBluetoothAlwaysUsageDescription</key>
+	<string>This app uses Bluetooth to communicate with MeshCore devices.</string>
+	<key>NSBluetoothPeripheralUsageDescription</key>
+	<string>This app uses Bluetooth to communicate with MeshCore devices.</string>
+	<key>NSCameraUsageDescription</key>
+	<string>This app uses the camera to scan QR codes for joining communities.</string>
+	<key>UIApplicationSceneManifest</key>
+	<dict>
+		<key>UIApplicationSupportsMultipleScenes</key>
+		<false/>
+		<key>UISceneConfigurations</key>
+		<dict>
+			<key>UIWindowSceneSessionRoleApplication</key>
+			<array>
+				<dict>
+					<key>UISceneClassName</key>
+					<string>UIWindowScene</string>
+					<key>UISceneConfigurationName</key>
+					<string>flutter</string>
+					<key>UISceneDelegateClassName</key>
+					<string>FlutterSceneDelegate</string>
+					<key>UISceneStoryboardFile</key>
+					<string>Main</string>
+				</dict>
+			</array>
+		</dict>
+	</dict>
+	<key>UIApplicationSupportsIndirectInputEvents</key>
+	<true/>
+	<key>UIBackgroundModes</key>
+	<array>
+		<string>bluetooth-central</string>
+	</array>
 	<key>UILaunchStoryboardName</key>
 	<string>LaunchScreen</string>
 	<key>UIMainStoryboardFile</key>
@@ -41,24 +81,5 @@
 		<string>UIInterfaceOrientationLandscapeLeft</string>
 		<string>UIInterfaceOrientationLandscapeRight</string>
 	</array>
-	<key>CADisableMinimumFrameDurationOnPhone</key>
-	<true/>
-	<key>UIApplicationSupportsIndirectInputEvents</key>
-	<true/>
-	<key>UIBackgroundModes</key>
-	<array>
-		<string>bluetooth-central</string>
-	</array>
-	<key>NSBluetoothAlwaysUsageDescription</key>
-	<string>This app uses Bluetooth to communicate with MeshCore devices.</string>
-	<key>NSBluetoothPeripheralUsageDescription</key>
-	<string>This app uses Bluetooth to communicate with MeshCore devices.</string>
-	<key>NSCameraUsageDescription</key>
-	<string>This app uses the camera to scan QR codes for joining communities.</string>
-	<key>LSApplicationQueriesSchemes</key>
-	<array>
-		<string>http</string>
-		<string>https</string>
-	</array>
 </dict>
 </plist>
@@ -0,0 +1,70 @@
+import 'dart:async';
+import 'dart:typed_data';
+
+import '../services/app_debug_log_service.dart';
+import '../services/tcp_transport_service.dart';
+
+/// Manages TCP transport for MeshCore devices.
+///
+/// Owns the [TcpTransportService] and TCP-specific connection state.
+/// The main [MeshCoreConnector] delegates all TCP operations here.
+class MeshCoreTcpConnector {
+  final TcpTransportService _service = TcpTransportService();
+  AppDebugLogService? _debugLog;
+  StreamSubscription<Uint8List>? _frameSubscription;
+
+  // --- Getters ---
+  String? get activeEndpoint => _service.activeEndpoint;
+  bool get isConnected => _service.isConnected;
+
+  // --- Configuration ---
+  void setDebugLogService(AppDebugLogService? service) {
+    _debugLog = service;
+    _service.setDebugLogService(service);
+  }
+
+  // --- Connection lifecycle ---
+  Future<void> connect({required String host, required int port}) async {
+    _debugLog?.info('TcpConnector.connect endpoint=$host:$port', tag: 'TCP');
+    await _frameSubscription?.cancel();
+    _frameSubscription = null;
+    await _service.connect(host: host, port: port);
+    _debugLog?.info(
+      'TcpConnector.connect done, endpoint=${_service.activeEndpoint}',
+      tag: 'TCP',
+    );
+  }
+
+  StreamSubscription<Uint8List> listenFrames({
+    required void Function(Uint8List) onFrame,
+    required void Function(Object, StackTrace?) onError,
+    required void Function() onDone,
+  }) {
+    _frameSubscription = _service.frameStream.listen(
+      onFrame,
+      onError: onError,
+      onDone: onDone,
+    );
+    return _frameSubscription!;
+  }
+
+  Future<void> cancelFrameSubscription() async {
+    await _frameSubscription?.cancel();
+    _frameSubscription = null;
+  }
+
+  Future<void> disconnect() async {
+    if (!_service.isConnected && _frameSubscription == null) return;
+    _debugLog?.info('TcpConnector.disconnect', tag: 'TCP');
+    await _frameSubscription?.cancel();
+    _frameSubscription = null;
+    await _service.disconnect();
+  }
+
+  Future<void> write(Uint8List data) => _service.write(data);
+
+  void dispose() {
+    _frameSubscription?.cancel();
+    _service.dispose();
+  }
+}
@@ -0,0 +1,79 @@
+import 'dart:typed_data';
+
+import '../services/app_debug_log_service.dart';
+import '../services/usb_serial_service.dart';
+
+/// Manages USB serial transport for MeshCore devices.
+///
+/// Owns the [UsbSerialService] and USB-specific connection state.
+/// The main [MeshCoreConnector] delegates all USB operations here.
+class MeshCoreUsbManager {
+  MeshCoreUsbManager();
+
+  final UsbSerialService _service = UsbSerialService();
+  AppDebugLogService? _debugLog;
+  String? _activePortKey;
+  String? _activePortLabel;
+
+  // --- Getters ---
+  String? get activePortKey => _activePortKey;
+  String? get activePortDisplayLabel => _activePortLabel ?? _activePortKey;
+  bool get isConnected => _service.isConnected;
+  Object? get lastError => _service.lastError;
+  Stream<Uint8List> get frameStream => _service.frameStream;
+
+  // --- Configuration ---
+  Future<List<String>> listPorts() => _service.listPorts();
+
+  void setRequestPortLabel(String label) => _service.setRequestPortLabel(label);
+
+  void setFallbackDeviceName(String label) =>
+      _service.setFallbackDeviceName(label);
+
+  void setDebugLogService(AppDebugLogService? service) {
+    _debugLog = service;
+    _service.setDebugLogService(service);
+  }
+
+  // --- Connection lifecycle ---
+  Future<void> connect({
+    required String portName,
+    int baudRate = 115200,
+  }) async {
+    _debugLog?.info(
+      'UsbManager.connect: portName=$portName baud=$baudRate',
+      tag: 'USB',
+    );
+    await _service.connect(portName: portName, baudRate: baudRate);
+    _activePortKey = _service.activePortKey ?? portName;
+    _activePortLabel = _service.activePortDisplayLabel ?? portName;
+    _debugLog?.info(
+      'UsbManager.connect: done, key=$_activePortKey label=$_activePortLabel',
+      tag: 'USB',
+    );
+  }
+
+  Future<void> disconnect() async {
+    if (!_service.isConnected && _activePortKey == null) {
+      return;
+    }
+    _debugLog?.info('UsbManager.disconnect', tag: 'USB');
+    await _service.disconnect();
+    _activePortKey = null;
+    _activePortLabel = null;
+  }
+
+  Future<void> write(Uint8List data) => _service.write(data);
+
+  Future<void> writeRaw(Uint8List data) => _service.writeRaw(data);
+
+  // --- Label management ---
+  void updateConnectedLabel(String selfName) {
+    _service.updateConnectedLabel(selfName);
+    _activePortLabel = _service.activePortDisplayLabel ?? _activePortLabel;
+  }
+
+  void dispose() {
+    _service.dispose();
+  }
+}
@@ -1,9 +1,12 @@
 import 'dart:convert';
 import 'dart:typed_data';

+import 'package:flutter/widgets.dart';
+
 // Buffer Reader - sequential binary data reader with pointer tracking
 class BufferReader {
  int _pointer = 0;
+  int _lastPointer = 0;
  final Uint8List _buffer;

  BufferReader(Uint8List data) : _buffer = Uint8List.fromList(data);
@@ -13,21 +16,31 @@ class BufferReader {
  int readByte() => readBytes(1)[0];

  Uint8List readBytes(int count) {
+    _lastPointer = _pointer;
+    if (_pointer + count > _buffer.length) {
+      throw RangeError(
+        'Attempted to read $count bytes at offset $_pointer, but only $remaining bytes remaining in buffer of length ${_buffer.length}',
+      );
+    }
    final data = _buffer.sublist(_pointer, _pointer + count);
    _pointer += count;
    return data;
  }

  void skipBytes(int count) {
+    _lastPointer = _pointer;
+    if (_pointer + count > _buffer.length) {
+      throw RangeError(
+        'Attempted to skip $count bytes at offset $_pointer, but only $remaining bytes remaining in buffer of length ${_buffer.length}',
+      );
+    }
    _pointer += count;
  }

  Uint8List readRemainingBytes() => readBytes(remaining);

-  String readString() =>
-      utf8.decode(readRemainingBytes(), allowMalformed: true);
-
-  String readCString(int maxLength) {
+  String readCStringGreedy(int maxLength) {
+    _lastPointer = _pointer;
    final value = <int>[];
    final bytes = readBytes(maxLength);
    for (final byte in bytes) {
@@ -41,6 +54,25 @@ class BufferReader {
    }
  }

+  String readCString({int maxLength = -1}) {
+    final backupPointer = _pointer;
+    final value = <int>[];
+    int counter = 0;
+    final maxLen = maxLength >= 0 ? maxLength : remaining;
+    while (counter < maxLen) {
+      final byte = readByte();
+      if (byte == 0) break;
+      value.add(byte);
+      counter++;
+    }
+    _lastPointer = backupPointer;
+    try {
+      return utf8.decode(Uint8List.fromList(value), allowMalformed: true);
+    } catch (e) {
+      return String.fromCharCodes(value); // Latin-1 fallback
+    }
+  }
+
  int readUInt8() => readBytes(1).buffer.asByteData().getUint8(0);
  int readInt8() => readBytes(1).buffer.asByteData().getInt8(0);
  int readUInt16LE() =>
@@ -62,6 +94,9 @@ class BufferReader {
    if ((value & 0x800000) != 0) value -= 0x1000000;
    return value;
  }
+
+  void resetPointer() => _pointer = 0;
+  void rewind() => _pointer = _lastPointer;
 }

 // Buffer Writer - accumulating binary data builder
@@ -104,23 +139,38 @@ class BufferWriter {
  }

  void writeHex(String hex) {
-    // Validate hex string length is even and not empty
-    if (hex.isEmpty || hex.length % 2 != 0) {
-      throw FormatException('Invalid hex string length: ${hex.length}');
-    }
-    List<int> result = [];
-    for (int i = 0; i < hex.length ~/ 2; i++) {
-      final hexByte = hex.substring(i * 2, i * 2 + 2);
-      final byte = int.tryParse(hexByte, radix: 16);
-      if (byte == null) {
-        throw FormatException(
-          'Invalid hex characters at position $i: $hexByte',
-        );
-      }
-      result.add(byte);
-    }
-    writeBytes(Uint8List.fromList(result));
+    writeBytes(hex2Uint8List(hex));
  }
+
+  void writeBytesPadded(Uint8List bytes, int totalLength) {
+    // Path data (64 bytes, zero-padded)
+    final bytesPadded = Uint8List(totalLength);
+    final len = bytes.length < totalLength ? bytes.length : totalLength;
+    if (bytes.isNotEmpty && len > 0) {
+      final copyLen = bytes.length < totalLength ? bytes.length : totalLength;
+      for (int i = 0; i < copyLen; i++) {
+        bytesPadded[i] = bytes[i];
+      }
+    }
+    writeBytes(bytesPadded);
+  }
+}
+
+Uint8List hex2Uint8List(String hex) {
+  // Validate hex string length is even and not empty
+  if (hex.isEmpty || hex.length % 2 != 0) {
+    throw FormatException('Invalid hex string length: ${hex.length}');
+  }
+  List<int> result = [];
+  for (int i = 0; i < hex.length ~/ 2; i++) {
+    final hexByte = hex.substring(i * 2, i * 2 + 2);
+    final byte = int.tryParse(hexByte, radix: 16);
+    if (byte == null) {
+      throw FormatException('Invalid hex characters at position $i: $hexByte');
+    }
+    result.add(byte);
+  }
+  return Uint8List.fromList(result);
 }

 // Command codes (to device)
@@ -151,22 +201,34 @@ const int cmdGetContactByKey = 30;
 const int cmdGetChannel = 31;
 const int cmdSetChannel = 32;
 const int cmdSendTracePath = 36;
-const int cmdGetRadioSettings = 57;
-const int cmdGetTelemetryReq = 39;
+const int cmdSetOtherParams = 38;
+const int cmdSendTelemetryReq = 39;
 const int cmdGetCustomVar = 40;
 const int cmdSetCustomVar = 41;
 const int cmdSendBinaryReq = 50;
+const int cmdGetStats = 56;
+const int cmdSendAnonReq = 57;
+const int cmdSetAutoAddConfig = 58;
+const int cmdGetAutoAddConfig = 59;
+const int cmdSetPathHashMode = 61;

 // Text message types
 const int txtTypePlain = 0;
 const int txtTypeCliData = 1;
+const int txtTypeSigned = 2;

 // Repeater request types (for server requests)
 const int reqTypeGetStatus = 0x01;
 const int reqTypeKeepAlive = 0x02;
 const int reqTypeGetTelemetry = 0x03;
 const int reqTypeGetAccessList = 0x05;
-const int reqTypeGetNeighbours = 0x06;
+const int reqTypeGetNeighbors = 0x06;
+
+Uint8List buildTelemetryBinaryPayload() {
+  // Room servers/repeaters read byte 1 as an inverse telemetry permission mask.
+  // Zero means "request every telemetry field allowed for this contact".
+  return Uint8List.fromList([reqTypeGetTelemetry, 0x00, 0x00, 0x00, 0x00]);
+}

 // Repeater response codes
 const int respServerLoginOk = 0;
@@ -189,8 +251,13 @@ const int respCodeDeviceInfo = 13;
 const int respCodeContactMsgRecvV3 = 16;
 const int respCodeChannelMsgRecvV3 = 17;
 const int respCodeChannelInfo = 18;
-const int respCodeRadioSettings = 25;
 const int respCodeCustomVars = 21;
+const int respCodeAutoAddConfig = 25;
+const int respCodeStats = 24;
+
+const int statsTypeCore = 0;
+const int statsTypeRadio = 1;
+const int statsTypePackets = 2;

 // Push codes (async from device)
 const int pushCodeAdvert = 0x80;
@@ -212,13 +279,54 @@ const int advTypeRepeater = 2;
 const int advTypeRoom = 3;
 const int advTypeSensor = 4;

+const int teleModeDeny = 0;
+const int teleModeAllowFlags = 1; // use contact.flags
+const int teleModeAllowAll = 2;
+
+// Payload Types
+const int payloadTypeREQ =
+    0x00; // request (prefixed with dest/src hashes, MAC) (enc data: timestamp, blob)
+const int payloadTypeRESPONSE =
+    0x01; // response to REQ or ANON_REQ (prefixed with dest/src hashes, MAC) (enc data: timestamp, blob)
+const int payloadTypeTXTMSG =
+    0x02; // a plain text message (prefixed with dest/src hashes, MAC) (enc data: timestamp, text)
+const int payloadTypeACK = 0x03; // a simple ack
+const int payloadTypeADVERT = 0x04; // a node advertising its Identity
+const int payloadTypeGRPTXT =
+    0x05; // an (unverified) group text message (prefixed with channel hash, MAC) (enc data: timestamp, "name: msg")
+const int payloadTypeGRPDATA =
+    0x06; // an (unverified) group datagram (prefixed with channel hash, MAC) (enc data: timestamp, blob)
+const int payloadTypeANONREQ =
+    0x07; // generic request (prefixed with dest_hash, ephemeral pub_key, MAC) (enc data: ...)
+const int payloadTypePATH =
+    0x08; // returned path (prefixed with dest/src hashes, MAC) (enc data: path, extra)
+const int payloadTypeTRACE = 0x09; // trace a path, collecting SNI for each hop
+const int payloadTypeMULTIPART = 0x0A; // packet is one of a set of packets
+const int payloadTypeCONTROL = 0x0B; // a control/discovery packet
+//...
+const int payloadTypeRawCustom =
+    0x0F; // custom packet as raw bytes, for applications with custom encryption, payloads, etc
+
+//auto-add flags
+const int autoAddOverwriteOldestFlag =
+    1 << 0; // 0x01 - overwrite oldest non-favourite when full
+const int autoAddChatFlag =
+    1 << 1; // 0x02 - auto-add Chat (Companion) (ADV_TYPE_CHAT)
+const int autoAddRepeaterFlag =
+    1 << 2; // 0x04 - auto-add Repeater (ADV_TYPE_REPEATER)
+const int autoAddRoomServerFlag =
+    1 << 3; // 0x08 - auto-add Room Server (ADV_TYPE_ROOM)
+const int autoAddSensorFlag =
+    1 << 4; // 0x10 - auto-add Sensor (ADV_TYPE_SENSOR)
+
 // Sizes
 const int pubKeySize = 32;
+const int signatureSize = 64;
 const int maxPathSize = 64;
 const int pathHashSize = 1;
 const int maxNameSize = 32;
 const int maxFrameSize = 172;
-const int appProtocolVersion = 3;
+const int appProtocolVersion = 4;
 // Matches firmware MAX_TEXT_LEN (10 * CIPHER_BLOCK_SIZE).
 const int maxTextPayloadBytes = 160;
 const int _sendTextMsgOverheadBytes =
@@ -255,13 +363,17 @@ int _minPositive(int a, int b) {
 const int contactPubKeyOffset = 1;
 const int contactTypeOffset = 33;
 const int contactFlagsOffset = 34;
+const int contactFlagFavorite = 0x01;
+const int contactFlagTeleBase = 0x02; // 'base' permission includes battery
+const int contactFlagTeleLoc = 0x04;
+const int contactFlagTeleEnv = 0x08; //access environment sensors
 const int contactPathLenOffset = 35;
 const int contactPathOffset = 36;
 const int contactNameOffset = 100;
 const int contactTimestampOffset = 132;
 const int contactLatOffset = 136;
 const int contactLonOffset = 140;
-const int contactLastmodOffset = 144;
+const int contactLastModOffset = 144;
 const int contactFrameSize = 148;

 // Message frame offsets
@@ -273,52 +385,44 @@ const int msgTextOffset = 38;
 class ParsedContactText {
  final Uint8List senderPrefix;
  final String text;
-
  const ParsedContactText({required this.senderPrefix, required this.text});
 }

 ParsedContactText? parseContactMessageText(Uint8List frame) {
  if (frame.isEmpty) return null;
-  final code = frame[0];
-  if (code != respCodeContactMsgRecv && code != respCodeContactMsgRecvV3) {
+
+  final message = BufferReader(frame);
+  try {
+    final code = message.readByte();
+    if (code != respCodeContactMsgRecv && code != respCodeContactMsgRecvV3) {
+      return null;
+    }
+
+    // Companion radio layout:
+    // [code][snr?][res?][res?][prefix x6][path_len][txt_type][timestamp x4][extra?][text...]
+    if (code == respCodeContactMsgRecvV3) {
+      // Skip SNR and reserved bytes in v3 layout
+      message.skipBytes(3);
+    }
+    final senderPrefix = message.readBytes(6); // public key
+    message.skipBytes(1); // path length
+    final textType = message.readByte();
+    message.skipBytes(4); // timestamp (4 bytes)
+
+    final shiftedType = textType >> 2;
+    final isSigned = shiftedType == txtTypeSigned || textType == txtTypeSigned;
+    if (isSigned) {
+      // Signed messages have a 4-byte signature after the timestamp, before the text
+      message.skipBytes(4);
+    }
+    final text = message.readCString();
+    if (text.isEmpty) return null;
+
+    return ParsedContactText(senderPrefix: senderPrefix, text: text);
+  } catch (e) {
+    debugPrint('Error parsing contact message text: $e');
    return null;
  }
-
-  // Companion radio layout:
-  // [code][snr?][res?][res?][prefix x6][path_len][txt_type][timestamp x4][extra?][text...]
-  final isV3 = code == respCodeContactMsgRecvV3;
-  final prefixOffset = isV3 ? 4 : 1;
-  const prefixLen = 6;
-  final txtTypeOffset = prefixOffset + prefixLen + 1;
-  final timestampOffset = txtTypeOffset + 1;
-  final baseTextOffset = timestampOffset + 4;
-  if (frame.length <= baseTextOffset) return null;
-
-  final flags = frame[txtTypeOffset];
-  final shiftedType = flags >> 2;
-  final rawType = flags;
-  final isPlain = shiftedType == txtTypePlain || rawType == txtTypePlain;
-  final isCli = shiftedType == txtTypeCliData || rawType == txtTypeCliData;
-  if (!isPlain && !isCli) {
-    return null;
-  }
-
-  var text = readCString(
-    frame,
-    baseTextOffset,
-    frame.length - baseTextOffset,
-  ).trim();
-  if (text.isEmpty && frame.length > baseTextOffset + 4) {
-    text = readCString(
-      frame,
-      baseTextOffset + 4,
-      frame.length - (baseTextOffset + 4),
-    ).trim();
-  }
-  if (text.isEmpty) return null;
-
-  final senderPrefix = frame.sublist(prefixOffset, prefixOffset + prefixLen);
-  return ParsedContactText(senderPrefix: senderPrefix, text: text);
 }

 // Helper to read uint32 little-endian
@@ -341,18 +445,9 @@ int readInt32LE(Uint8List data, int offset) {
  return val;
 }

-// Helper to read null-terminated UTF-8 string
-String readCString(Uint8List data, int offset, int maxLen) {
-  int end = offset;
-  while (end < offset + maxLen && end < data.length && data[end] != 0) {
-    end++;
-  }
-  try {
-    return utf8.decode(data.sublist(offset, end), allowMalformed: true);
-  } catch (e) {
-    // Fallback to Latin-1 if UTF-8 decoding fails
-    return String.fromCharCodes(data.sublist(offset, end));
-  }
+// Helper to convert uint32 to hex string
+String ackHashToHex(int ackHash) {
+  return ackHash.toRadixString(16).padLeft(8, '0');
 }

 // Helper to convert public key to hex string
@@ -362,8 +457,13 @@ String pubKeyToHex(Uint8List pubKey) {

 // Helper to convert hex string to public key
 Uint8List hexToPubKey(String hex) {
+  if (hex.length != pubKeySize * 2) {
+    throw FormatException(
+      'Public key hex must be ${pubKeySize * 2} chars, got ${hex.length}',
+    );
+  }
  final result = Uint8List(pubKeySize);
-  for (int i = 0; i < pubKeySize && i * 2 + 1 < hex.length; i++) {
+  for (int i = 0; i < pubKeySize; i++) {
    result[i] = int.parse(hex.substring(i * 2, i * 2 + 2), radix: 16);
  }
  return result;
@@ -412,7 +512,7 @@ Uint8List buildSendTextMsgFrame(
  final writer = BufferWriter();
  writer.writeByte(cmdSendTxtMsg);
  writer.writeByte(txtTypePlain);
-  writer.writeByte(attempt.clamp(0, 3));
+  writer.writeByte(attempt.clamp(0, 255));
  writer.writeUInt32LE(timestamp);
  writer.writeBytes(recipientPubKey.sublist(0, 6));
  writer.writeString(text);
@@ -472,6 +572,17 @@ Uint8List buildGetBattAndStorageFrame() {
  return Uint8List.fromList([cmdGetBattAndStorage]);
 }

+/// Companion radio stats: [56][statsType] where statsType is statsTypeCore/Radio/Packets.
+Uint8List buildGetStatsFrame(int statsType) {
+  return Uint8List.fromList([cmdGetStats, statsType & 0xFF]);
+}
+
+/// Path hash width on air: [61][0][mode], mode 0..2 → (mode+1) bytes per hop hash.
+Uint8List buildSetPathHashModeFrame(int mode) {
+  final m = mode.clamp(0, 2);
+  return Uint8List.fromList([cmdSetPathHashMode, 0, m]);
+}
+
 // Build CMD_SET_DEVICE_TIME frame
 Uint8List buildSetDeviceTimeFrame(int timestamp) {
  final writer = BufferWriter();
@@ -550,18 +661,29 @@ Uint8List buildSetChannelFrame(int channelIndex, String name, Uint8List psk) {
 }

 // Build CMD_SET_RADIO_PARAMS frame
-// Format: [cmd][freq x4][bw x4][sf][cr]
+// Format: [cmd][freq x4][bw x4][sf][cr] (pre-v9)
+//         [cmd][freq x4][bw x4][sf][cr][repeat] (firmware v9+)
 // freq: frequency in Hz (300000-2500000)
 // bw: bandwidth in Hz (7000-500000)
 // sf: spreading factor (5-12)
 // cr: coding rate (5-8)
-Uint8List buildSetRadioParamsFrame(int freqHz, int bwHz, int sf, int cr) {
+// clientRepeat: enable off-grid packet repeat (firmware v9+, omit for older)
+Uint8List buildSetRadioParamsFrame(
+  int freqHz,
+  int bwHz,
+  int sf,
+  int cr, {
+  bool? clientRepeat,
+}) {
  final writer = BufferWriter();
  writer.writeByte(cmdSetRadioParams);
  writer.writeUInt32LE(freqHz);
  writer.writeUInt32LE(bwHz);
  writer.writeByte(sf);
  writer.writeByte(cr);
+  if (clientRepeat != null) {
+    writer.writeByte(clientRepeat ? 1 : 0);
+  }
  return writer.toBytes();
 }

@@ -581,14 +703,17 @@ Uint8List buildResetPathFrame(Uint8List pubKey) {
 }

 // Build CMD_ADD_UPDATE_CONTACT frame to set custom path
-// Format: [cmd][pub_key x32][type][flags][path_len][path x64][name x32][timestamp x4]
+// Format: [cmd][pub_key x32][type][flags][path_len][path x64][name x32][Lat? x4, Lon? x4][timestamp? x4]
 Uint8List buildUpdateContactPathFrame(
  Uint8List pubKey,
-  Uint8List customPath,
+  Uint8List path,
  int pathLen, {
  int type = 1, // ADV_TYPE_CHAT
  int flags = 0,
  String name = '',
+  double? lat,
+  double? lon,
+  DateTime? lastModified,
 }) {
  final writer = BufferWriter();
  writer.writeByte(cmdAddUpdateContact);
@@ -597,17 +722,7 @@ Uint8List buildUpdateContactPathFrame(
  writer.writeByte(flags);
  writer.writeByte(pathLen);

-  // Path data (64 bytes, zero-padded)
-  final pathPadded = Uint8List(maxPathSize);
-  if (customPath.isNotEmpty && pathLen > 0) {
-    final copyLen = customPath.length < maxPathSize
-        ? customPath.length
-        : maxPathSize;
-    for (int i = 0; i < copyLen; i++) {
-      pathPadded[i] = customPath[i];
-    }
-  }
-  writer.writeBytes(pathPadded);
+  writer.writeBytesPadded(path, maxPathSize);

  // Name (32 bytes, null-padded)
  writer.writeCString(name, maxNameSize);
@@ -616,6 +731,21 @@ Uint8List buildUpdateContactPathFrame(
  final timestamp = DateTime.now().millisecondsSinceEpoch ~/ 1000;
  writer.writeUInt32LE(timestamp);

+  // Optional [Lat x4, Lon x4][timestamp x4] tail per the doc comment above.
+  // Emit 8 bytes of position (zero-filled when only lastModified is provided)
+  // followed by an optional 4-byte timestamp. Earlier code emitted the
+  // position block twice, which corrupted the tail and caused the firmware
+  // to parse the second lat as the timestamp. See #427.
+  final hasLocation = lat != null && lon != null;
+  if (hasLocation || lastModified != null) {
+    writer.writeInt32LE(hasLocation ? (lat * 1e6).round() : 0);
+    writer.writeInt32LE(hasLocation ? (lon * 1e6).round() : 0);
+    if (lastModified != null) {
+      final lastModifiedTimestamp = lastModified.millisecondsSinceEpoch ~/ 1000;
+      writer.writeUInt32LE(lastModifiedTimestamp);
+    }
+  }
+
  return writer.toBytes();
 }

@@ -628,16 +758,15 @@ Uint8List buildGetContactByKeyFrame(Uint8List pubKey) {
  return writer.toBytes();
 }

-// Build CMD_GET_RADIO_SETTINGS frame
-Uint8List buildGetRadioSettingsFrame() {
-  return Uint8List.fromList([cmdGetRadioSettings]);
-}
-
 //Build CMD_GET_CUSTOM_VARS frame
 Uint8List buildGetCustomVarsFrame() {
  return Uint8List.fromList([cmdGetCustomVar]);
 }

+Uint8List buildGetAutoAddFlagsFrame() {
+  return Uint8List.fromList([cmdGetAutoAddConfig]);
+}
+
 // Calculate LoRa airtime for a packet
 // Based on Semtech SX127x datasheet formula
 // Returns airtime in milliseconds
@@ -717,7 +846,7 @@ Uint8List buildSendCliCommandFrame(
  final writer = BufferWriter();
  writer.writeByte(cmdSendTxtMsg);
  writer.writeByte(txtTypeCliData);
-  writer.writeByte(attempt.clamp(0, 3));
+  writer.writeByte(attempt.clamp(0, 255));
  writer.writeUInt32LE(timestamp);
  writer.writeBytes(repeaterPubKey.sublist(0, 6));
  writer.writeString(command);
@@ -762,10 +891,10 @@ Uint8List buildExportContactFrame(Uint8List pubKey) {

 // Build a import contact frame
 // [cmd][contact_frame x98+]
-Uint8List buildImportContactFrame(String contactFrame) {
+Uint8List buildImportContactFrame(Uint8List contactFrame) {
  final writer = BufferWriter();
  writer.writeByte(cmdImportContact);
-  writer.writeHex(contactFrame);
+  writer.writeBytes(contactFrame);
  return writer.toBytes();
 }

@@ -777,3 +906,57 @@ Uint8List buildZeroHopContact(Uint8List pubKey) {
  writer.writeBytes(pubKey);
  return writer.toBytes();
 }
+
+// Build CMD_SET_OTHER_PARAMS frame
+// Format: [cmd][allowTelemetryFlags][advertLocationPolicy][multiAcks]
+Uint8List buildSetOtherParamsFrame(
+  int allowTelemetryFlags,
+  int advertLocationPolicy,
+  int multiAcks,
+) {
+  final writer = BufferWriter();
+  writer.writeByte(cmdSetOtherParams);
+  //Going forward the app will just set Auto Add Contacts to disabled, and use the filter flags
+  //Allow Auto Add Contacts use inverted logic (0x01 = disabled, 0x00 = enabled).
+  writer.writeByte(0x01);
+  writer.writeByte(allowTelemetryFlags); // Allow Telemetry Flags
+  writer.writeByte(advertLocationPolicy); // Advertisement Location Policy
+  writer.writeByte(multiAcks); // Multi Acknowledgements
+  return writer.toBytes();
+}
+
+// Build CMD_SET_AUTO_ADD_CONFIG frame
+// Format: [cmd][flags]
+Uint8List buildSetAutoAddConfigFrame({
+  required bool autoAddChat,
+  required bool autoAddRepeater,
+  required bool autoAddRoomServer,
+  required bool autoAddSensor,
+  required bool overwriteOldest,
+}) {
+  final writer = BufferWriter();
+  writer.writeByte(cmdSetAutoAddConfig);
+  int flags = 0;
+  if (autoAddChat) flags |= autoAddChatFlag;
+  if (autoAddRepeater) flags |= autoAddRepeaterFlag;
+  if (autoAddRoomServer) flags |= autoAddRoomServerFlag;
+  if (autoAddSensor) flags |= autoAddSensorFlag;
+  if (overwriteOldest) flags |= autoAddOverwriteOldestFlag;
+  writer.writeByte(flags);
+  return writer.toBytes();
+}
+
+//Build CMD_SEND_TELEMETRY_REQ
+// Format: [cmd][reserved x3][pub_key? x32]
+Uint8List buildSendTelemetryReq(Uint8List? pubKey) {
+  final writer = BufferWriter();
+  writer.writeByte(cmdSendTelemetryReq);
+
+  if (pubKey != null && pubKey.length == pubKeySize) {
+    writer.writeBytes(Uint8List(3)); // reserved bytes
+    writer.writeBytes(pubKey);
+  } else {
+    writer.writeBytes(Uint8List(3)); // reserved bytes
+  }
+  return writer.toBytes();
+}
@@ -0,0 +1,20 @@
+class MeshCoreUuids {
+  static const String service = "6e400001-b5a3-f393-e0a9-e50e24dcca9e";
+  static const String rxCharacteristic = "6e400002-b5a3-f393-e0a9-e50e24dcca9e";
+  static const String txCharacteristic = "6e400003-b5a3-f393-e0a9-e50e24dcca9e";
+
+  /// Known advertised-name prefixes used by stock MeshCore firmware builds.
+  /// Discovery no longer filters on these (it filters on the [service] UUID so
+  /// that community forks with custom names are still found); kept for
+  /// reference and possible future display heuristics.
+  static const List<String> deviceNamePrefixes = [
+    "MeshCore-",
+    "Whisper-",
+    "WisCore-",
+    "Seeed",
+    "Lilygo",
+    "HT-",
+    "LowMesh_MC_",
+    "NRF52",
+  ];
+}
@@ -1,4 +1,6 @@
 import 'dart:typed_data';
+import 'package:meshcore_open/utils/app_logger.dart';
+
 import '../connector/meshcore_protocol.dart';

 class CayenneLpp {
@@ -84,180 +86,392 @@ class CayenneLpp {
  static List<Map<String, dynamic>> parse(Uint8List bytes) {
    final buffer = BufferReader(bytes);
    final telemetry = <Map<String, dynamic>>[];
+    try {
+      while (buffer.remaining >= 2) {
+        final channel = buffer.readUInt8();
+        final type = buffer.readUInt8();

-    while (buffer.remaining >= 2) {
-      final channel = buffer.readUInt8();
-      final type = buffer.readUInt8();
+        if (channel == 0 && type == 0) {
+          break;
+        }

-      if (channel == 0 && type == 0) {
-        break;
-      }
-
-      switch (type) {
-        case lppGenericSensor:
-          telemetry.add({
-            'channel': channel,
-            'type': type,
-            'value': buffer.readUInt32BE(),
-          });
-          break;
-        case lppLuminosity:
-          telemetry.add({
-            'channel': channel,
-            'type': type,
-            'value': buffer.readUInt16BE(),
-          });
-          break;
-        case lppPresence:
-          telemetry.add({
-            'channel': channel,
-            'type': type,
-            'value': buffer.readUInt8(),
-          });
-          break;
-        case lppTemperature:
-          telemetry.add({
-            'channel': channel,
-            'type': type,
-            'value': buffer.readInt16BE() / 10,
-          });
-          break;
-        case lppRelativeHumidity:
-          telemetry.add({
-            'channel': channel,
-            'type': type,
-            'value': buffer.readUInt8() / 2,
-          });
-          break;
-        case lppBarometricPressure:
-          telemetry.add({
-            'channel': channel,
-            'type': type,
-            'value': buffer.readUInt16BE() / 10,
-          });
-          break;
-        case lppVoltage:
-          telemetry.add({
-            'channel': channel,
-            'type': type,
-            'value': buffer.readInt16BE() / 100,
-          });
-          break;
-        case lppCurrent:
-          telemetry.add({
-            'channel': channel,
-            'type': type,
-            'value': buffer.readInt16BE() / 1000,
-          });
-          break;
-        case lppPercentage:
-          telemetry.add({
-            'channel': channel,
-            'type': type,
-            'value': buffer.readUInt8(),
-          });
-          break;
-        case lppConcentration:
-          telemetry.add({
-            'channel': channel,
-            'type': type,
-            'value': buffer.readUInt16BE(),
-          });
-          break;
-        case lppPower:
-          telemetry.add({
-            'channel': channel,
-            'type': type,
-            'value': buffer.readUInt16BE(),
-          });
-          break;
-        case lppGps:
-          telemetry.add({
-            'channel': channel,
-            'type': type,
-            'value': {
-              'latitude': buffer.readInt24BE() / 10000,
-              'longitude': buffer.readInt24BE() / 10000,
-              'altitude': buffer.readInt24BE() / 100,
-            },
-          });
-          break;
-        default:
-          return telemetry;
+        switch (type) {
+          case lppDigitalInput:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt8(),
+            });
+            break;
+          case lppDigitalOutput:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt8(),
+            });
+            break;
+          case lppAnalogInput:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readInt16BE() / 100,
+            });
+            break;
+          case lppAnalogOutput:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readInt16BE() / 100,
+            });
+            break;
+          case lppGenericSensor:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt32BE(),
+            });
+            break;
+          case lppLuminosity:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt16BE(),
+            });
+            break;
+          case lppPresence:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt8(),
+            });
+            break;
+          case lppTemperature:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readInt16BE() / 10,
+            });
+            break;
+          case lppRelativeHumidity:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt8() / 2,
+            });
+            break;
+          case lppAccelerometer:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': {
+                'x': buffer.readInt16BE() / 1000,
+                'y': buffer.readInt16BE() / 1000,
+                'z': buffer.readInt16BE() / 1000,
+              },
+            });
+            break;
+          case lppBarometricPressure:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt16BE() / 10,
+            });
+            break;
+          case lppAltitude:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readInt16BE(),
+            });
+            break;
+          case lppVoltage:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readInt16BE() / 100,
+            });
+            break;
+          case lppCurrent:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readInt16BE() / 1000,
+            });
+            break;
+          case lppFrequency:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt32BE(),
+            });
+            break;
+          case lppPercentage:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt8(),
+            });
+            break;
+          case lppConcentration:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt16BE(),
+            });
+            break;
+          case lppPower:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt16BE(),
+            });
+            break;
+          case lppDistance:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt32BE() / 1000,
+            });
+            break;
+          case lppEnergy:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt32BE() / 1000,
+            });
+            break;
+          case lppDirection:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt16BE(),
+            });
+            break;
+          case lppUnixTime:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt32BE(),
+            });
+            break;
+          case lppGyrometer:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': {
+                'x': buffer.readInt16BE() / 100,
+                'y': buffer.readInt16BE() / 100,
+                'z': buffer.readInt16BE() / 100,
+              },
+            });
+            break;
+          case lppColour:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': {
+                'red': buffer.readUInt8(),
+                'green': buffer.readUInt8(),
+                'blue': buffer.readUInt8(),
+              },
+            });
+            break;
+          case lppGps:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': {
+                'latitude': buffer.readInt24BE() / 10000,
+                'longitude': buffer.readInt24BE() / 10000,
+                'altitude': buffer.readInt24BE() / 100,
+              },
+            });
+            break;
+          case lppSwitch:
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': buffer.readUInt8(),
+            });
+            break;
+          case lppPolyline:
+            final size = buffer.readUInt8();
+            telemetry.add({
+              'channel': channel,
+              'type': type,
+              'value': {
+                'size': size,
+                'data': _bytesToHex(_readPolylinePayload(buffer, size)),
+              },
+            });
+            break;
+          default:
+            return telemetry;
+        }
      }
+      return telemetry;
+    } catch (e) {
+      // Handle parsing errors, possibly due to malformed data
+      appLogger.error('Error parsing Cayenne LPP data: $e');
+      // Return any telemetry parsed so far to preserve partial data
+      return telemetry;
    }
-
-    return telemetry;
  }

  static List<Map<String, dynamic>> parseByChannel(Uint8List bytes) {
    final buffer = BufferReader(bytes);
    final Map<int, Map<String, dynamic>> channels = {};
+    try {
+      while (buffer.remaining >= 2) {
+        final channel = buffer.readUInt8();
+        final type = buffer.readUInt8();

-    while (buffer.remaining >= 2) {
-      final channel = buffer.readUInt8();
-      final type = buffer.readUInt8();
+        // Optional: stop on padding (00 00)
+        if (channel == 0 && type == 0) {
+          break;
+        }

-      // Optional: stop on padding (00 00)
-      if (channel == 0 && type == 0) {
-        break;
+        final channelData = channels.putIfAbsent(
+          channel,
+          () => {'channel': channel, 'values': <String, dynamic>{}},
+        );
+
+        switch (type) {
+          case lppDigitalInput:
+            channelData['values']['digitalInput'] = buffer.readUInt8();
+            break;
+          case lppDigitalOutput:
+            channelData['values']['digitalOutput'] = buffer.readUInt8();
+            break;
+          case lppAnalogInput:
+            channelData['values']['analogInput'] = buffer.readInt16BE() / 100.0;
+            break;
+          case lppAnalogOutput:
+            channelData['values']['analogOutput'] =
+                buffer.readInt16BE() / 100.0;
+            break;
+          case lppGenericSensor:
+            channelData['values']['generic'] = buffer.readUInt32BE();
+            break;
+          case lppLuminosity:
+            channelData['values']['luminosity'] = buffer.readUInt16BE();
+            break;
+          case lppPresence:
+            channelData['values']['presence'] = buffer.readUInt8() != 0;
+            break;
+          case lppTemperature:
+            channelData['values']['temperature'] = buffer.readInt16BE() / 10.0;
+            break;
+          case lppRelativeHumidity:
+            channelData['values']['humidity'] = buffer.readUInt8() / 2.0;
+            break;
+          case lppAccelerometer:
+            channelData['values']['accelerometer'] = {
+              'x': buffer.readInt16BE() / 1000.0,
+              'y': buffer.readInt16BE() / 1000.0,
+              'z': buffer.readInt16BE() / 1000.0,
+            };
+            break;
+          case lppBarometricPressure:
+            channelData['values']['pressure'] = buffer.readUInt16BE() / 10.0;
+            break;
+          case lppAltitude:
+            // MeshCore encodes standalone barometric altitude as LPP type 121.
+            channelData['values']['altitude'] = buffer.readInt16BE();
+            break;
+          case lppVoltage:
+            channelData['values']['voltage'] = buffer.readInt16BE() / 100.0;
+            break;
+          case lppCurrent:
+            channelData['values']['current'] = buffer.readInt16BE() / 1000.0;
+            break;
+          case lppFrequency:
+            channelData['values']['frequency'] = buffer.readUInt32BE();
+            break;
+          case lppPercentage:
+            channelData['values']['percentage'] = buffer.readUInt8();
+            break;
+          case lppConcentration:
+            channelData['values']['concentration'] = buffer.readUInt16BE();
+            break;
+          case lppPower:
+            channelData['values']['power'] = buffer.readUInt16BE();
+            break;
+          case lppDistance:
+            channelData['values']['distance'] = buffer.readUInt32BE() / 1000.0;
+            break;
+          case lppEnergy:
+            channelData['values']['energy'] = buffer.readUInt32BE() / 1000.0;
+            break;
+          case lppDirection:
+            channelData['values']['direction'] = buffer.readUInt16BE();
+            break;
+          case lppUnixTime:
+            channelData['values']['time'] = buffer.readUInt32BE();
+            break;
+          case lppGyrometer:
+            channelData['values']['gyrometer'] = {
+              'x': buffer.readInt16BE() / 100.0,
+              'y': buffer.readInt16BE() / 100.0,
+              'z': buffer.readInt16BE() / 100.0,
+            };
+            break;
+          case lppColour:
+            channelData['values']['colour'] = {
+              'red': buffer.readUInt8(),
+              'green': buffer.readUInt8(),
+              'blue': buffer.readUInt8(),
+            };
+            break;
+          case lppGps:
+            channelData['values']['gps'] = {
+              'latitude': buffer.readInt24BE() / 10000.0,
+              'longitude': buffer.readInt24BE() / 10000.0,
+              'altitude': buffer.readInt24BE() / 100.0,
+            };
+            break;
+          case lppSwitch:
+            channelData['values']['switch'] = buffer.readUInt8() != 0;
+            break;
+          case lppPolyline:
+            final size = buffer.readUInt8();
+            channelData['values']['polyline'] = {
+              'size': size,
+              'data': _bytesToHex(_readPolylinePayload(buffer, size)),
+            };
+            break;
+          default:
+            // Stop parsing to avoid losing alignment on an unknown LPP type.
+            return _sortedChannelValues(channels);
+        }
      }

-      final channelData = channels.putIfAbsent(
-        channel,
-        () => {'channel': channel, 'values': <String, dynamic>{}},
-      );
-
-      switch (type) {
-        case lppGenericSensor:
-          channelData['values']['generic'] = buffer.readUInt32BE();
-          break;
-        case lppLuminosity:
-          channelData['values']['luminosity'] = buffer.readUInt16BE();
-          break;
-        case lppPresence:
-          channelData['values']['presence'] = buffer.readUInt8() != 0;
-          break;
-        case lppTemperature:
-          channelData['values']['temperature'] = buffer.readInt16BE() / 10.0;
-          break;
-        case lppRelativeHumidity:
-          channelData['values']['humidity'] = buffer.readUInt8() / 2.0;
-          break;
-        case lppBarometricPressure:
-          channelData['values']['pressure'] = buffer.readUInt16BE() / 10.0;
-          break;
-        case lppVoltage:
-          channelData['values']['voltage'] = buffer.readInt16BE() / 100.0;
-          break;
-        case lppCurrent:
-          channelData['values']['current'] = buffer.readInt16BE() / 1000.0;
-          break;
-        case lppPercentage:
-          channelData['values']['percentage'] = buffer.readUInt8();
-          break;
-        case lppConcentration:
-          channelData['values']['concentration'] = buffer.readUInt16BE();
-          break;
-        case lppPower:
-          channelData['values']['power'] = buffer.readUInt16BE();
-          break;
-        case lppGps:
-          channelData['values']['gps'] = {
-            'latitude': buffer.readInt24BE() / 10000.0,
-            'longitude': buffer.readInt24BE() / 10000.0,
-            'altitude': buffer.readInt24BE() / 100.0,
-          };
-          break;
-        // Add more types as needed...
-        default:
-          // Unknown type: skip or handle error?
-          continue;
-      }
+      return _sortedChannelValues(channels);
+    } catch (e) {
+      // Handle parsing errors, possibly due to malformed data
+      appLogger.error('Error parsing Cayenne LPP data: $e');
+      // Preserve any fields parsed before the malformed value.
+      return _sortedChannelValues(channels);
    }
+  }

-    final List<Map<String, dynamic>> channelsOut = channels.values.toList();
+  static Uint8List _readPolylinePayload(BufferReader buffer, int size) {
+    final declaredPayloadSize = size > 0 ? size - 1 : 0;
+    final availablePayloadSize = declaredPayloadSize <= buffer.remaining
+        ? declaredPayloadSize
+        : buffer.remaining;
+    return buffer.readBytes(availablePayloadSize);
+  }
+
+  static List<Map<String, dynamic>> _sortedChannelValues(
+    Map<int, Map<String, dynamic>> channels,
+  ) {
+    final channelsOut = channels.values.toList();
    channelsOut.sort((a, b) => a['channel'].compareTo(b['channel']));
    return channelsOut;
  }
+
+  static String _bytesToHex(Uint8List bytes) {
+    return bytes.map((b) => b.toRadixString(16).padLeft(2, '0')).join();
+  }
 }
@@ -49,6 +49,25 @@ class ChatScrollController extends ScrollController {
    }
  }

+  /// Jumps toward an off-screen message so that lazy ListView.builder builds
+  /// items near it. Only visible + cacheExtent items have real heights, so we
+  /// use proportion of maxScrollExtent (itself an estimate from built items'
+  /// avg height). Call [onJumped] on the next frame to ensureVisible/scroll
+  /// to the exact target.
+  void jumpToEstimatedOffset({
+    required int unreadCount,
+    required int totalMessages,
+    required VoidCallback onJumped,
+  }) {
+    if (!hasClients || totalMessages == 0) return;
+    final maxExtent = position.maxScrollExtent;
+    final jumpOffset = maxExtent * (unreadCount / totalMessages);
+    if (jumpOffset > 100) {
+      jumpTo(jumpOffset);
+    }
+    WidgetsBinding.instance.addPostFrameCallback((_) => onJumped());
+  }
+
  void scrollToBottomIfAtBottom() {
    // Only scroll if jump button is NOT showing (i.e., already at bottom)
    if (!showJumpToBottom.value && hasClients && position.maxScrollExtent > 0) {
@@ -0,0 +1,59 @@
+import 'package:flutter/material.dart';
+
+import '../connector/meshcore_protocol.dart';
+import '../utils/emoji_utils.dart';
+
+IconData contactTypeIcon(int type) {
+  switch (type) {
+    case advTypeChat:
+      return Icons.chat;
+    case advTypeRepeater:
+      return Icons.cell_tower;
+    case advTypeRoom:
+      return Icons.group;
+    case advTypeSensor:
+      return Icons.sensors;
+    default:
+      return Icons.device_unknown;
+  }
+}
+
+Color contactTypeColor(int type) {
+  switch (type) {
+    case advTypeChat:
+      return Colors.blue;
+    case advTypeRepeater:
+      return Colors.orange;
+    case advTypeRoom:
+      return Colors.purple;
+    case advTypeSensor:
+      return Colors.green;
+    default:
+      return Colors.grey;
+  }
+}
+
+Color colorForName(String name) {
+  const colors = [
+    Colors.blue,
+    Colors.green,
+    Colors.orange,
+    Colors.purple,
+    Colors.pink,
+    Colors.teal,
+    Colors.indigo,
+    Colors.cyan,
+    Colors.amber,
+    Colors.deepOrange,
+  ];
+  return colors[name.hashCode.abs() % colors.length];
+}
+
+String firstCharacterOrEmoji(String name) {
+  if (name.isEmpty) return '?';
+  final emoji = firstEmoji(name);
+  if (emoji != null) return emoji;
+  final runes = name.runes.toList();
+  if (runes.isEmpty) return '?';
+  return String.fromCharCode(runes[0]).toUpperCase();
+}
@@ -0,0 +1,63 @@
+class Cyr2Lat {
+  static Map<String, String> _charMap = {
+    'А': 'A',
+    'В': 'B',
+    'Е': 'E',
+    'Ё': 'E',
+    'З': '3',
+    'К': 'K',
+    'М': 'M',
+    'Н': 'H',
+    'О': 'O',
+    'Р': 'P',
+    'С': 'C',
+    'Т': 'T',
+    'Х': 'X',
+    'Ь': 'b',
+    'а': 'a',
+    'е': 'e',
+    'ё': 'e',
+    'о': 'o',
+    'р': 'p',
+    'с': 'c',
+    'у': 'y',
+    'х': 'x',
+  };
+
+  static final RegExp _prefixRegExp = RegExp(r'\@\[[\S\s]+\] ');
+
+  static void setCharMap(Map<String, String> charMap) {
+    _charMap = Map.from(charMap);
+  }
+
+  static String encode(String text) {
+    if (text.isEmpty) return text;
+    final buffer = StringBuffer();
+
+    final senderName = extractSenderName(text);
+    final msgText = removeSenderName(text);
+
+    for (final rune in msgText.runes) {
+      final char = String.fromCharCode(rune);
+      buffer.write(_charMap[char] ?? char);
+    }
+
+    return senderName + buffer.toString();
+  }
+
+  static String removeSenderName(String text) {
+    final match = _prefixRegExp.matchAsPrefix(text);
+    if (match != null) {
+      return text.substring(match.end);
+    }
+    return text;
+  }
+
+  static String extractSenderName(String text) {
+    final match = _prefixRegExp.matchAsPrefix(text);
+    if (match != null) {
+      return match.group(0) ?? '';
+    }
+    return '';
+  }
+}
@@ -0,0 +1,38 @@
+class GifHelper {
+  /// Parse a known GIF format, which can be any of:
+  /// g:GIFID
+  /// https://media.giphy.com/media/GIFID/giphy.gif
+  /// https://giphy.com/gifs/Optional-title-with-dashes-GIFID
+  ///
+  /// GIFID is a Giphy GIF ID. The https:// is optional (and
+  /// can also be http://). The giphy.com/gifs form can also
+  /// include a trailing slash.
+  ///
+  /// Returns null if text is not a valid GIF format
+  static String? parseGif(String text) {
+    final trimmed = text.trim();
+    final match = RegExp(r'^g:([A-Za-z0-9_-]+)$').firstMatch(trimmed);
+    if (match != null) {
+      return match.group(1);
+    }
+    final directUrlMatch = RegExp(
+      r'^(?:https?:\/\/)?media\.giphy\.com\/media\/([A-Za-z0-9_-]+)\/giphy\.gif$',
+    ).firstMatch(trimmed);
+    if (directUrlMatch != null) {
+      return directUrlMatch.group(1);
+    }
+    // Giphy understands page URLs with just the ID, or any string and a
+    // dash before the ID, and redirects to a page with a dash-separated
+    // title, a dash, and the ID. IDs in this form *probably* can't
+    // contain dashes.
+    final pageMatch = RegExp(
+      r'^(?:https?:\/\/)?giphy\.com\/gifs\/(?:[^/?]*-)?([A-Za-z0-9_]+)\/?$',
+    ).firstMatch(trimmed);
+    return pageMatch?.group(1);
+  }
+
+  /// Encode a GIF in a format that parseGif() can parse.
+  static String encodeGif(String gifId) {
+    return 'g:$gifId';
+  }
+}
@@ -1,8 +1,51 @@
 import 'package:flutter/material.dart';
+import 'package:flutter_linkify/flutter_linkify.dart';
 import 'package:url_launcher/url_launcher.dart';
 import '../l10n/l10n.dart';
+import '../utils/platform_info.dart';
+import '../helpers/snack_bar_builder.dart';

 class LinkHandler {
+  static TextStyle defaultLinkStyle(BuildContext context, TextStyle base) {
+    final brightness = Theme.of(context).brightness;
+    final orange = brightness == Brightness.dark
+        ? const Color(0xFFFFB74D)
+        : const Color(0xFFE65100);
+    return base.copyWith(color: orange, decoration: TextDecoration.underline);
+  }
+
+  /// Returns a [SelectableLinkify] on desktop or a [Linkify] on mobile.
+  static Widget buildLinkifyText({
+    required BuildContext context,
+    required String text,
+    required TextStyle style,
+    TextStyle? linkStyle,
+  }) {
+    final effectiveLinkStyle = linkStyle ?? defaultLinkStyle(context, style);
+    const options = LinkifyOptions(humanize: false, defaultToHttps: false);
+    const linkifiers = [UrlLinkifier(), EmailLinkifier()];
+    void onOpen(LinkableElement link) => handleLinkTap(context, link.url);
+
+    if (PlatformInfo.isDesktop) {
+      return SelectableLinkify(
+        text: text,
+        style: style,
+        linkStyle: effectiveLinkStyle,
+        options: options,
+        linkifiers: linkifiers,
+        onOpen: onOpen,
+      );
+    }
+    return Linkify(
+      text: text,
+      style: style,
+      linkStyle: effectiveLinkStyle,
+      options: options,
+      linkifiers: linkifiers,
+      onOpen: onOpen,
+    );
+  }
+
  static Future<void> handleLinkTap(BuildContext context, String url) async {
    // Show confirmation dialog
    final shouldOpen = await showDialog<bool>(
@@ -51,21 +94,19 @@ class LinkHandler {
      final uri = Uri.parse(url);
      if (!await launchUrl(uri, mode: LaunchMode.externalApplication)) {
        if (context.mounted) {
-          ScaffoldMessenger.of(context).showSnackBar(
-            SnackBar(
-              content: Text(context.l10n.chat_couldNotOpenLink(url)),
-              backgroundColor: Colors.red,
-            ),
+          showDismissibleSnackBar(
+            context,
+            content: Text(context.l10n.chat_couldNotOpenLink(url)),
+            backgroundColor: Colors.red,
          );
        }
      }
    } catch (e) {
      if (context.mounted) {
-        ScaffoldMessenger.of(context).showSnackBar(
-          SnackBar(
-            content: Text(context.l10n.chat_invalidLink),
-            backgroundColor: Colors.red,
-          ),
+        showDismissibleSnackBar(
+          context,
+          content: Text(context.l10n.chat_invalidLink),
+          backgroundColor: Colors.red,
        );
      }
    }
@@ -0,0 +1,36 @@
+import '../models/contact.dart';
+import '../connector/meshcore_protocol.dart';
+
+class PathHelper {
+  static String formatPathHex(List<int> pathBytes) {
+    return pathBytes
+        .map((b) => b.toRadixString(16).padLeft(2, '0').toUpperCase())
+        .join(',');
+  }
+
+  static String hopHex(int byte) {
+    return byte.toRadixString(16).padLeft(2, '0').toUpperCase();
+  }
+
+  static String? hopName(int byte, List<Contact> allContacts) {
+    final matches = allContacts
+        .where(
+          (c) =>
+              c.publicKey.first == byte &&
+              (c.type == advTypeRepeater || c.type == advTypeRoom),
+        )
+        .toList();
+    if (matches.isEmpty) return null;
+    if (matches.length == 1) return matches.first.name;
+    return matches.map((c) => c.name).join(' | ');
+  }
+
+  static String resolvePathNames(
+    List<int> pathBytes,
+    List<Contact> allContacts,
+  ) {
+    return pathBytes
+        .map((b) => hopName(b, allContacts) ?? hopHex(b))
+        .join(' \u2192 ');
+  }
+}
@@ -0,0 +1,70 @@
+import 'package:latlong2/latlong.dart';
+
+import '../connector/meshcore_protocol.dart';
+import '../models/contact.dart';
+
+class PathHopResolver {
+  const PathHopResolver._();
+
+  static List<Contact?> resolve({
+    required List<int> pathBytes,
+    required List<Contact> contacts,
+    LatLng? endpoint,
+    bool resolveFromEnd = false,
+  }) {
+    final candidatesByPrefix = <int, List<Contact>>{};
+    for (final contact in contacts) {
+      if (contact.publicKey.isEmpty) continue;
+      if (contact.type != advTypeRepeater && contact.type != advTypeRoom) {
+        continue;
+      }
+      candidatesByPrefix
+          .putIfAbsent(contact.publicKey.first, () => <Contact>[])
+          .add(contact);
+    }
+    for (final candidates in candidatesByPrefix.values) {
+      candidates.sort((a, b) => b.lastSeen.compareTo(a.lastSeen));
+    }
+
+    final resolved = List<Contact?>.filled(pathBytes.length, null);
+    final indexes = resolveFromEnd
+        ? List<int>.generate(pathBytes.length, (i) => pathBytes.length - 1 - i)
+        : List<int>.generate(pathBytes.length, (i) => i);
+    final distance = Distance();
+    var previousPosition = endpoint;
+
+    for (final index in indexes) {
+      final candidates = candidatesByPrefix[pathBytes[index]];
+      if (candidates == null || candidates.isEmpty) continue;
+
+      var bestIndex = 0;
+      if (previousPosition != null && candidates.length > 1) {
+        double? nearestDistance;
+        for (var i = 0; i < candidates.length; i++) {
+          final position = _positionOf(candidates[i]);
+          if (position == null) continue;
+          final candidateDistance = distance(previousPosition, position);
+          if (nearestDistance == null || candidateDistance < nearestDistance) {
+            nearestDistance = candidateDistance;
+            bestIndex = i;
+          }
+        }
+      }
+
+      final contact = candidates.removeAt(bestIndex);
+      resolved[index] = contact;
+      previousPosition = _positionOf(contact) ?? previousPosition;
+    }
+
+    return resolved;
+  }
+
+  static LatLng? _positionOf(Contact contact) {
+    if (!contact.hasLocation ||
+        contact.latitude == null ||
+        contact.longitude == null) {
+      return null;
+    }
+    return LatLng(contact.latitude!, contact.longitude!);
+  }
+}
@@ -8,6 +8,50 @@ class ReactionInfo {
 }

 class ReactionHelper {
+  /// Apply a reaction to a list of messages by matching the reaction hash.
+  ///
+  /// [messages] - the message list to search
+  /// [reactionInfo] - the parsed reaction
+  /// [getTimestampSecs] - extract timestamp seconds from a message
+  /// [getSenderName] - extract sender name for hash (null for 1:1 implicit)
+  /// [getMessageText] - extract message text
+  /// [getReactions] - extract current reactions map
+  /// [shouldSkip] - filter function to skip messages (e.g., skip outgoing for incoming reactions)
+  /// [updateMessage] - callback to update the message at index with new reactions
+  ///
+  /// Returns whether a match was found.
+  static bool applyReaction<T>({
+    required List<T> messages,
+    required ReactionInfo reactionInfo,
+    required int Function(T) getTimestampSecs,
+    required String? Function(T) getSenderName,
+    required String Function(T) getMessageText,
+    required Map<String, int> Function(T) getReactions,
+    required bool Function(T) shouldSkip,
+    required void Function(int index, Map<String, int> newReactions)
+    updateMessage,
+  }) {
+    final targetHash = reactionInfo.targetHash;
+    for (int i = messages.length - 1; i >= 0; i--) {
+      final msg = messages[i];
+      if (shouldSkip(msg)) continue;
+
+      final msgHash = computeReactionHash(
+        getTimestampSecs(msg),
+        getSenderName(msg),
+        getMessageText(msg),
+      );
+      if (msgHash == targetHash) {
+        final currentReactions = Map<String, int>.from(getReactions(msg));
+        currentReactions[reactionInfo.emoji] =
+            (currentReactions[reactionInfo.emoji] ?? 0) + 1;
+        updateMessage(i, currentReactions);
+        return true;
+      }
+    }
+    return false;
+  }
+
  static List<String>? _cachedEmojis;

  /// Combined list of all reaction emojis in fixed order.
@@ -65,4 +109,9 @@ class ReactionHelper {

    return ReactionInfo(targetHash: match.group(1)!, emoji: emoji);
  }
+
+  /// Encode a reaction message that parseReaction() can parse.
+  static String encodeReaction(String hash, String emojiIndex) {
+    return 'r:$hash:$emojiIndex';
+  }
 }
@@ -0,0 +1,68 @@
+import 'package:flutter/material.dart';
+
+// showDismissibleSnackBar shows  a [SnackBar] with tap to dismiss
+// all other properties are default and optional
+void showDismissibleSnackBar(
+  BuildContext context, {
+  Key? key,
+  required Widget content,
+  Color? backgroundColor,
+  double? elevation,
+  EdgeInsetsGeometry? margin,
+  EdgeInsetsGeometry? padding,
+  double? width,
+  ShapeBorder? shape,
+  HitTestBehavior? hitTestBehavior,
+  SnackBarBehavior? behavior,
+  SnackBarAction? action,
+  double? actionOverflowThreshold,
+  bool? showCloseIcon,
+  Color? closeIconColor,
+  Duration? duration,
+  bool? persist,
+  Animation<double>? animation,
+  void Function()? onVisible,
+  DismissDirection? dismissDirection,
+  Clip? clipBehavior,
+}) {
+  // Callers often reach here after an async gap; the context may already be
+  // unmounted, or deactivated (popped but not yet disposed) — ancestor
+  // lookups on a deactivated element throw. Showing nothing is the right
+  // outcome in both cases.
+  if (!context.mounted) return;
+  var isActive = true;
+  assert(() {
+    isActive = (context as Element).debugIsActive;
+    return true;
+  }());
+  if (!isActive) return;
+  final messenger = ScaffoldMessenger.maybeOf(context);
+  if (messenger == null) return;
+  messenger.showSnackBar(
+    SnackBar(
+      key: key,
+      content: GestureDetector(
+        onTap: () => messenger.hideCurrentSnackBar(),
+        child: content,
+      ),
+      backgroundColor: backgroundColor,
+      elevation: elevation,
+      margin: margin,
+      padding: padding,
+      width: width,
+      shape: shape,
+      hitTestBehavior: hitTestBehavior,
+      behavior: behavior,
+      action: action,
+      actionOverflowThreshold: actionOverflowThreshold,
+      showCloseIcon: showCloseIcon,
+      closeIconColor: closeIconColor,
+      duration: duration ?? const Duration(seconds: 4),
+      persist: persist,
+      animation: animation,
+      onVisible: onVisible,
+      dismissDirection: dismissDirection ?? DismissDirection.down,
+      clipBehavior: clipBehavior ?? Clip.hardEdge,
+    ),
+  );
+}
@@ -4,8 +4,14 @@ import 'package:flutter/services.dart';

 class Utf8LengthLimitingTextInputFormatter extends TextInputFormatter {
  final int maxBytes;
+  final String Function(String)? encoder;

-  const Utf8LengthLimitingTextInputFormatter(this.maxBytes);
+  const Utf8LengthLimitingTextInputFormatter(this.maxBytes, {this.encoder});
+
+  int _effectiveByteLength(String text) {
+    final effective = encoder != null ? encoder!(text) : text;
+    return utf8.encode(effective).length;
+  }

  @override
  TextEditingValue formatEditUpdate(
@@ -13,8 +19,7 @@ class Utf8LengthLimitingTextInputFormatter extends TextInputFormatter {
    TextEditingValue newValue,
  ) {
    if (maxBytes <= 0) return oldValue;
-    final bytes = utf8.encode(newValue.text);
-    if (bytes.length <= maxBytes) return newValue;
+    if (_effectiveByteLength(newValue.text) <= maxBytes) return newValue;

    final truncated = _truncateToMaxBytes(newValue.text, maxBytes);
    return TextEditingValue(
@@ -25,6 +30,14 @@ class Utf8LengthLimitingTextInputFormatter extends TextInputFormatter {
  }

  String _truncateToMaxBytes(String text, int limit) {
+    if (encoder != null) {
+      final runes = text.runes.toList();
+      while (runes.isNotEmpty &&
+          _effectiveByteLength(String.fromCharCodes(runes)) > maxBytes) {
+        runes.removeLast();
+      }
+      return String.fromCharCodes(runes);
+    }
    final buffer = StringBuffer();
    var used = 0;
    for (final rune in text.runes) {
@@ -0,0 +1,22 @@
+import 'package:flutter/material.dart';
+import 'package:material_symbols_icons/material_symbols_icons.dart';
+
+class LosIcon extends StatelessWidget {
+  final double size;
+  final Color? color;
+
+  const LosIcon({super.key, this.size = 24, this.color});
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    final iconTheme = IconTheme.of(context);
+    final iconColor =
+        color ??
+        iconTheme.color ??
+        theme.iconTheme.color ??
+        theme.colorScheme.onSurface;
+
+    return Icon(Symbols.elevation, size: size, color: iconColor);
+  }
+}
@@ -0,0 +1,36 @@
+import '../connector/meshcore_protocol.dart';
+import '../models/contact.dart';
+import 'app_localizations.dart';
+
+/// UI-level localization helpers for [Contact].
+///
+/// Kept out of the model layer so `Contact` does not depend on
+/// `AppLocalizations`. Use these from widgets/screens; for logs and
+/// non-UI export use `Contact.typeLabelRaw`.
+extension ContactLocalization on Contact {
+  String typeLabel(AppLocalizations l10n) {
+    switch (type) {
+      case advTypeChat:
+        return l10n.contact_typeChat;
+      case advTypeRepeater:
+        return l10n.contact_typeRepeater;
+      case advTypeRoom:
+        return l10n.contact_typeRoom;
+      case advTypeSensor:
+        return l10n.contact_typeSensor;
+      default:
+        return l10n.contact_typeUnknown;
+    }
+  }
+
+  String pathLabel(AppLocalizations l10n) {
+    if (pathOverride != null) {
+      if (pathOverride! < 0) return l10n.chat_floodForced;
+      if (pathOverride == 0) return l10n.chat_directForced;
+      return l10n.chat_hopsForced(pathOverride!);
+    }
+    if (pathLength < 0) return l10n.channelPath_floodPath;
+    if (pathLength == 0) return l10n.chat_direct;
+    return l10n.chat_hopsCount(pathLength);
+  }
+}
@@ -1,8 +1,13 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_localizations/flutter_localizations.dart';
+import 'package:flutter/foundation.dart';
+import 'package:flutter/services.dart';
 import 'l10n/app_localizations.dart';
 import 'package:provider/provider.dart';

+import 'screens/chrome_required_screen.dart';
+import 'utils/platform_info.dart';
+
 import 'connector/meshcore_connector.dart';
 import 'screens/scanner_screen.dart';
 import 'services/storage_service.dart';
@@ -14,12 +19,26 @@ import 'services/ble_debug_log_service.dart';
 import 'services/app_debug_log_service.dart';
 import 'services/background_service.dart';
 import 'services/map_tile_cache_service.dart';
+import 'services/chat_text_scale_service.dart';
+import 'services/translation_service.dart';
+import 'services/ui_view_state_service.dart';
+import 'services/timeout_prediction_service.dart';
 import 'storage/prefs_manager.dart';
+import 'theme/mesh_theme.dart';
 import 'utils/app_logger.dart';

 void main() async {
  WidgetsFlutterBinding.ensureInitialized();

+  // On desktop, debugPrint is not suppressed in release builds and every
+  // call is a synchronous stdout write. The connector logs heavily on hot
+  // paths (frame handling, queue/channel sync), which shows up as syscall
+  // overhead on low-end Linux machines (issue #202). The in-app debug log
+  // screens are unaffected — they store entries themselves.
+  if (kReleaseMode) {
+    debugPrint = (String? message, {int? wrapWidth}) {};
+  }
+
  // Initialize SharedPreferences cache
  await PrefsManager.initialize();

@@ -33,6 +52,10 @@ void main() async {
  final appDebugLogService = AppDebugLogService();
  final backgroundService = BackgroundService();
  final mapTileCacheService = MapTileCacheService();
+  final chatTextScaleService = ChatTextScaleService();
+  final translationService = TranslationService(appSettingsService);
+  final uiViewStateService = UiViewStateService();
+  final timeoutPredictionService = TimeoutPredictionService(storage);

  // Load settings
  await appSettingsService.loadSettings();
@@ -47,15 +70,26 @@ void main() async {
  final notificationService = NotificationService();
  await notificationService.initialize();
  await backgroundService.initialize();
+  backgroundService.setLanguageOverrideProvider(
+    () => appSettingsService.settings.languageOverride,
+  );
+  _registerThirdPartyLicenses();
+
+  await chatTextScaleService.initialize();
+  await translationService.refreshDownloadedModels();
+  await uiViewStateService.initialize();
+  await timeoutPredictionService.initialize();

  // Wire up connector with services
  connector.initialize(
    retryService: retryService,
    pathHistoryService: pathHistoryService,
    appSettingsService: appSettingsService,
+    translationService: translationService,
    bleDebugLogService: bleDebugLogService,
    appDebugLogService: appDebugLogService,
    backgroundService: backgroundService,
+    timeoutPredictionService: timeoutPredictionService,
  );

  await connector.loadContactCache();
@@ -76,10 +110,35 @@ void main() async {
      bleDebugLogService: bleDebugLogService,
      appDebugLogService: appDebugLogService,
      mapTileCacheService: mapTileCacheService,
+      chatTextScaleService: chatTextScaleService,
+      translationService: translationService,
+      uiViewStateService: uiViewStateService,
+      timeoutPredictionService: timeoutPredictionService,
    ),
  );
 }

+void _registerThirdPartyLicenses() {
+  LicenseRegistry.addLicense(() async* {
+    yield const LicenseEntryWithLineBreaks(
+      <String>['Open-Meteo Elevation API Data'],
+      '''
+Data used by LOS elevation lookups is provided by Open-Meteo.
+
+Open-Meteo terms and attribution:
+https://open-meteo.com/en/terms
+
+Elevation API:
+https://open-meteo.com/en/docs/elevation-api
+
+Attribution license reference:
+Creative Commons Attribution 4.0 International (CC BY 4.0)
+https://creativecommons.org/licenses/by/4.0/
+''',
+    );
+  });
+}
+
 class MeshCoreApp extends StatelessWidget {
  final MeshCoreConnector connector;
  final MessageRetryService retryService;
@@ -89,6 +148,10 @@ class MeshCoreApp extends StatelessWidget {
  final BleDebugLogService bleDebugLogService;
  final AppDebugLogService appDebugLogService;
  final MapTileCacheService mapTileCacheService;
+  final ChatTextScaleService chatTextScaleService;
+  final TranslationService translationService;
+  final UiViewStateService uiViewStateService;
+  final TimeoutPredictionService timeoutPredictionService;

  const MeshCoreApp({
    super.key,
@@ -100,6 +163,10 @@ class MeshCoreApp extends StatelessWidget {
    required this.bleDebugLogService,
    required this.appDebugLogService,
    required this.mapTileCacheService,
+    required this.chatTextScaleService,
+    required this.translationService,
+    required this.uiViewStateService,
+    required this.timeoutPredictionService,
  });

  @override
@@ -112,8 +179,12 @@ class MeshCoreApp extends StatelessWidget {
        ChangeNotifierProvider.value(value: appSettingsService),
        ChangeNotifierProvider.value(value: bleDebugLogService),
        ChangeNotifierProvider.value(value: appDebugLogService),
+        ChangeNotifierProvider.value(value: chatTextScaleService),
+        ChangeNotifierProvider.value(value: translationService),
+        ChangeNotifierProvider.value(value: uiViewStateService),
        Provider.value(value: storage),
        Provider.value(value: mapTileCacheService),
+        ChangeNotifierProvider.value(value: timeoutPredictionService),
      ],
      child: Consumer<AppSettingsService>(
        builder: (context, settingsService, child) {
@@ -130,23 +201,8 @@ class MeshCoreApp extends StatelessWidget {
            locale: _localeFromSetting(
              settingsService.settings.languageOverride,
            ),
-            theme: ThemeData(
-              colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
-              useMaterial3: true,
-              snackBarTheme: const SnackBarThemeData(
-                behavior: SnackBarBehavior.floating,
-              ),
-            ),
-            darkTheme: ThemeData(
-              colorScheme: ColorScheme.fromSeed(
-                seedColor: Colors.blue,
-                brightness: Brightness.dark,
-              ),
-              useMaterial3: true,
-              snackBarTheme: const SnackBarThemeData(
-                behavior: SnackBarBehavior.floating,
-              ),
-            ),
+            theme: MeshTheme.light(),
+            darkTheme: MeshTheme.dark(),
            themeMode: _themeModeFromSetting(
              settingsService.settings.themeMode,
            ),
@@ -154,9 +210,14 @@ class MeshCoreApp extends StatelessWidget {
              // Update notification service with resolved locale
              final locale = Localizations.localeOf(context);
              NotificationService().setLocale(locale);
-              return child ?? const SizedBox.shrink();
+              return AnnotatedRegion<SystemUiOverlayStyle>(
+                value: _systemUiOverlayStyle(context),
+                child: child ?? const SizedBox.shrink(),
+              );
            },
-            home: const ScannerScreen(),
+            home: (PlatformInfo.isWeb && !PlatformInfo.isChrome)
+                ? const ChromeRequiredScreen()
+                : const ScannerScreen(),
          );
        },
      ),
@@ -174,6 +235,24 @@ class MeshCoreApp extends StatelessWidget {
    }
  }

+  SystemUiOverlayStyle _systemUiOverlayStyle(BuildContext context) {
+    final theme = Theme.of(context);
+    final colorScheme = theme.colorScheme;
+    final isDark = theme.brightness == Brightness.dark;
+    final iconBrightness = isDark ? Brightness.light : Brightness.dark;
+
+    // Keep Android system bars aligned with the resolved Flutter theme.
+    return SystemUiOverlayStyle(
+      statusBarColor: Colors.transparent,
+      statusBarIconBrightness: iconBrightness,
+      statusBarBrightness: isDark ? Brightness.dark : Brightness.light,
+      systemNavigationBarColor: colorScheme.surface,
+      systemNavigationBarIconBrightness: iconBrightness,
+      systemNavigationBarDividerColor: colorScheme.surface,
+      systemNavigationBarContrastEnforced: false,
+    );
+  }
+
  Locale? _localeFromSetting(String? languageCode) {
    if (languageCode == null) return null;
    return Locale(languageCode);
@@ -1,3 +1,79 @@
+import 'translation_support.dart';
+
+enum UnitSystem { metric, imperial }
+
+extension UnitSystemValue on UnitSystem {
+  String get value {
+    switch (this) {
+      case UnitSystem.imperial:
+        return 'imperial';
+      case UnitSystem.metric:
+        return 'metric';
+    }
+  }
+}
+
+const Map<String, String> defaultCyr2LatCharMap = {
+  'А': 'A',
+  'В': 'B',
+  'Е': 'E',
+  'Ё': 'E',
+  'З': '3',
+  'К': 'K',
+  'М': 'M',
+  'Н': 'H',
+  'О': 'O',
+  'Р': 'P',
+  'С': 'C',
+  'Т': 'T',
+  'Х': 'X',
+  'Ь': 'b',
+  'а': 'a',
+  'е': 'e',
+  'ё': 'e',
+  'о': 'o',
+  'р': 'p',
+  'с': 'c',
+  'у': 'y',
+  'х': 'x',
+};
+
+class Cyr2LatProfile {
+  final String id;
+  final String name;
+  final Map<String, String> charMap;
+
+  Cyr2LatProfile({required this.id, required this.name, required this.charMap});
+
+  Map<String, dynamic> toJson() {
+    return {'id': id, 'name': name, 'char_map': charMap};
+  }
+
+  factory Cyr2LatProfile.fromJson(Map<String, dynamic> json) {
+    return Cyr2LatProfile(
+      id: json['id'] as String,
+      name: json['name'] as String,
+      charMap:
+          (json['char_map'] as Map?)?.map(
+            (key, value) => MapEntry(key.toString(), value.toString()),
+          ) ??
+          {},
+    );
+  }
+
+  Cyr2LatProfile copyWith({
+    String? id,
+    String? name,
+    Map<String, String>? charMap,
+  }) {
+    return Cyr2LatProfile(
+      id: id ?? this.id,
+      name: name ?? this.name,
+      charMap: charMap ?? this.charMap,
+    );
+  }
+}
+
 class AppSettings {
  static const Object _unset = Object();

@@ -5,10 +81,13 @@ class AppSettings {
  final bool mapShowRepeaters;
  final bool mapShowChatNodes;
  final bool mapShowOtherNodes;
+  final bool mapShowOverlaps;
  final double mapTimeFilterHours; // 0 = all time
  final bool mapKeyPrefixEnabled;
  final String mapKeyPrefix;
  final bool mapShowMarkers;
+  final bool mapShowGuessedLocations;
+  final bool enableMessageTracing;
  final Map<String, double>? mapCacheBounds;
  final int mapCacheMinZoom;
  final int mapCacheMaxZoom;
@@ -17,20 +96,52 @@ class AppSettings {
  final bool notifyOnNewChannelMessage;
  final bool notifyOnNewAdvert;
  final bool autoRouteRotationEnabled;
+  final double maxRouteWeight;
+  final double initialRouteWeight;
+  final double routeWeightSuccessIncrement;
+  final double routeWeightFailureDecrement;
+  final int maxMessageRetries;
  final String themeMode;
  final String? languageOverride; // null = system default
  final bool appDebugLogEnabled;
  final Map<String, String> batteryChemistryByDeviceId;
+  final Map<String, String> batteryChemistryByRepeaterId;
+  final UnitSystem unitSystem;
+  final Set<String> mutedChannels;
+  final bool mapShowDiscoveryContacts;
+  final String tcpServerAddress;
+  final int tcpServerPort;
+  final bool jumpToOldestUnread;
+  final bool translationEnabled;
+  final bool autoTranslateIncomingMessages;
+  final String? translationTargetLanguageCode;
+  final bool composerTranslationEnabled;
+  final String? translationModelSourceUrl;
+  final String? translationSelectedModelId;
+  final List<TranslationModelRecord> translationDownloadedModels;
+  final List<Cyr2LatProfile> cyr2latProfiles;
+  final String selectedCyr2latProfileId;
+
+  Map<String, String> get cyr2latCharMap {
+    final profile = cyr2latProfiles.firstWhere(
+      (p) => p.id == selectedCyr2latProfileId,
+      orElse: () => cyr2latProfiles.first,
+    );
+    return profile.charMap;
+  }

  AppSettings({
    this.clearPathOnMaxRetry = false,
    this.mapShowRepeaters = true,
    this.mapShowChatNodes = true,
    this.mapShowOtherNodes = true,
+    this.mapShowOverlaps = false,
    this.mapTimeFilterHours = 0, // Default to all time
    this.mapKeyPrefixEnabled = false,
    this.mapKeyPrefix = '',
    this.mapShowMarkers = true,
+    this.mapShowGuessedLocations = true,
+    this.enableMessageTracing = true,
    this.mapCacheBounds,
    this.mapCacheMinZoom = 10,
    this.mapCacheMaxZoom = 15,
@@ -38,12 +149,46 @@ class AppSettings {
    this.notifyOnNewMessage = true,
    this.notifyOnNewChannelMessage = true,
    this.notifyOnNewAdvert = true,
-    this.autoRouteRotationEnabled = false,
+    this.autoRouteRotationEnabled = true,
+    this.maxRouteWeight = 5.0,
+    this.initialRouteWeight = 3.0,
+    this.routeWeightSuccessIncrement = 0.5,
+    this.routeWeightFailureDecrement = 0.2,
+    this.maxMessageRetries = 5,
    this.themeMode = 'system',
    this.languageOverride,
    this.appDebugLogEnabled = false,
    Map<String, String>? batteryChemistryByDeviceId,
-  }) : batteryChemistryByDeviceId = batteryChemistryByDeviceId ?? {};
+    Map<String, String>? batteryChemistryByRepeaterId,
+    this.unitSystem = UnitSystem.metric,
+    Set<String>? mutedChannels,
+    this.mapShowDiscoveryContacts = true,
+    this.tcpServerAddress = '',
+    this.tcpServerPort = 0,
+    this.jumpToOldestUnread = false,
+    this.translationEnabled = false,
+    this.autoTranslateIncomingMessages = true,
+    this.translationTargetLanguageCode,
+    this.composerTranslationEnabled = false,
+    this.translationModelSourceUrl,
+    this.translationSelectedModelId,
+    List<TranslationModelRecord>? translationDownloadedModels,
+    List<Cyr2LatProfile>? cyr2latProfiles,
+    String? selectedCyr2latProfileId,
+  }) : batteryChemistryByDeviceId = batteryChemistryByDeviceId ?? {},
+       batteryChemistryByRepeaterId = batteryChemistryByRepeaterId ?? {},
+       mutedChannels = mutedChannels ?? {},
+       translationDownloadedModels = translationDownloadedModels ?? const [],
+       cyr2latProfiles =
+           cyr2latProfiles ??
+           [
+             Cyr2LatProfile(
+               id: 'default',
+               name: 'Default',
+               charMap: defaultCyr2LatCharMap,
+             ),
+           ],
+       selectedCyr2latProfileId = selectedCyr2latProfileId ?? 'default';

  Map<String, dynamic> toJson() {
    return {
@@ -51,10 +196,13 @@ class AppSettings {
      'map_show_repeaters': mapShowRepeaters,
      'map_show_chat_nodes': mapShowChatNodes,
      'map_show_other_nodes': mapShowOtherNodes,
+      'map_show_overlaps': mapShowOverlaps,
      'map_time_filter_hours': mapTimeFilterHours,
      'map_key_prefix_enabled': mapKeyPrefixEnabled,
      'map_key_prefix': mapKeyPrefix,
      'map_show_markers': mapShowMarkers,
+      'map_show_guessed_locations': mapShowGuessedLocations,
+      'enable_message_tracing': enableMessageTracing,
      'map_cache_bounds': mapCacheBounds,
      'map_cache_min_zoom': mapCacheMinZoom,
      'map_cache_max_zoom': mapCacheMaxZoom,
@@ -63,24 +211,60 @@ class AppSettings {
      'notify_on_new_channel_message': notifyOnNewChannelMessage,
      'notify_on_new_advert': notifyOnNewAdvert,
      'auto_route_rotation_enabled': autoRouteRotationEnabled,
+      'max_route_weight': maxRouteWeight,
+      'initial_route_weight': initialRouteWeight,
+      'route_weight_success_increment': routeWeightSuccessIncrement,
+      'route_weight_failure_decrement': routeWeightFailureDecrement,
+      'max_message_retries': maxMessageRetries,
      'theme_mode': themeMode,
      'language_override': languageOverride,
      'app_debug_log_enabled': appDebugLogEnabled,
      'battery_chemistry_by_device_id': batteryChemistryByDeviceId,
+      'battery_chemistry_by_repeater_id': batteryChemistryByRepeaterId,
+      'unit_system': unitSystem.value,
+      'muted_channels': mutedChannels.toList(),
+      'map_show_discovery_contacts': mapShowDiscoveryContacts,
+      'tcp_server_address': tcpServerAddress,
+      'tcp_server_port': tcpServerPort,
+      'jump_to_oldest_unread': jumpToOldestUnread,
+      'translation_enabled': translationEnabled,
+      'auto_translate_incoming_messages': autoTranslateIncomingMessages,
+      'translation_target_language_code': translationTargetLanguageCode,
+      'composer_translation_enabled': composerTranslationEnabled,
+      'translation_model_source_url': translationModelSourceUrl,
+      'translation_selected_model_id': translationSelectedModelId,
+      'translation_downloaded_models': translationDownloadedModels
+          .map((model) => model.toJson())
+          .toList(),
+      'cyr2lat_profiles': cyr2latProfiles
+          .map((profile) => profile.toJson())
+          .toList(),
+      'selected_cyr2lat_profile_id': selectedCyr2latProfileId,
    };
  }

  factory AppSettings.fromJson(Map<String, dynamic> json) {
+    UnitSystem parseUnitSystem(dynamic value) {
+      if (value is String && value.toLowerCase() == 'imperial') {
+        return UnitSystem.imperial;
+      }
+      return UnitSystem.metric;
+    }
+
    return AppSettings(
      clearPathOnMaxRetry: json['clear_path_on_max_retry'] as bool? ?? false,
      mapShowRepeaters: json['map_show_repeaters'] as bool? ?? true,
      mapShowChatNodes: json['map_show_chat_nodes'] as bool? ?? true,
      mapShowOtherNodes: json['map_show_other_nodes'] as bool? ?? true,
+      mapShowOverlaps: json['map_show_overlaps'] as bool? ?? false,
      mapTimeFilterHours:
          (json['map_time_filter_hours'] as num?)?.toDouble() ?? 0,
      mapKeyPrefixEnabled: json['map_key_prefix_enabled'] as bool? ?? false,
      mapKeyPrefix: json['map_key_prefix'] as String? ?? '',
      mapShowMarkers: json['map_show_markers'] as bool? ?? true,
+      mapShowGuessedLocations:
+          json['map_show_guessed_locations'] as bool? ?? true,
+      enableMessageTracing: json['enable_message_tracing'] as bool? ?? true,
      mapCacheBounds: (json['map_cache_bounds'] as Map?)?.map(
        (key, value) => MapEntry(key.toString(), (value as num).toDouble()),
      ),
@@ -92,7 +276,15 @@ class AppSettings {
          json['notify_on_new_channel_message'] as bool? ?? true,
      notifyOnNewAdvert: json['notify_on_new_advert'] as bool? ?? true,
      autoRouteRotationEnabled:
-          json['auto_route_rotation_enabled'] as bool? ?? false,
+          json['auto_route_rotation_enabled'] as bool? ?? true,
+      maxRouteWeight: (json['max_route_weight'] as num?)?.toDouble() ?? 5.0,
+      initialRouteWeight:
+          (json['initial_route_weight'] as num?)?.toDouble() ?? 3.0,
+      routeWeightSuccessIncrement:
+          (json['route_weight_success_increment'] as num?)?.toDouble() ?? 0.5,
+      routeWeightFailureDecrement:
+          (json['route_weight_failure_decrement'] as num?)?.toDouble() ?? 0.2,
+      maxMessageRetries: json['max_message_retries'] as int? ?? 5,
      themeMode: json['theme_mode'] as String? ?? 'system',
      languageOverride: json['language_override'] as String?,
      appDebugLogEnabled: json['app_debug_log_enabled'] as bool? ?? false,
@@ -101,6 +293,74 @@ class AppSettings {
            (key, value) => MapEntry(key.toString(), value.toString()),
          ) ??
          {},
+      batteryChemistryByRepeaterId:
+          (json['battery_chemistry_by_repeater_id'] as Map?)?.map(
+            (key, value) => MapEntry(key.toString(), value.toString()),
+          ) ??
+          {},
+      unitSystem: parseUnitSystem(json['unit_system']),
+      mutedChannels:
+          ((json['muted_channels'] as List?)
+              ?.map((e) => e.toString())
+              .toSet()) ??
+          {},
+      mapShowDiscoveryContacts:
+          json['map_show_discovery_contacts'] as bool? ?? true,
+      tcpServerAddress: json['tcp_server_address'] as String? ?? '',
+      tcpServerPort: json['tcp_server_port'] as int? ?? 0,
+      jumpToOldestUnread: json['jump_to_oldest_unread'] as bool? ?? false,
+      translationEnabled: json['translation_enabled'] as bool? ?? false,
+      autoTranslateIncomingMessages:
+          json['auto_translate_incoming_messages'] as bool? ?? true,
+      translationTargetLanguageCode:
+          json['translation_target_language_code'] as String?,
+      composerTranslationEnabled:
+          json['composer_translation_enabled'] as bool? ?? false,
+      translationModelSourceUrl:
+          json['translation_model_source_url'] as String?,
+      translationSelectedModelId:
+          json['translation_selected_model_id'] as String?,
+      translationDownloadedModels:
+          (json['translation_downloaded_models'] as List<dynamic>?)
+              ?.map(
+                (entry) => TranslationModelRecord.fromJson(
+                  Map<String, dynamic>.from(entry as Map),
+                ),
+              )
+              .toList() ??
+          const [],
+      cyr2latProfiles:
+          (json['cyr2lat_profiles'] as List<dynamic>?)
+              ?.map(
+                (entry) => Cyr2LatProfile.fromJson(
+                  Map<String, dynamic>.from(entry as Map),
+                ),
+              )
+              .toList() ??
+          // Backward compatibility: if old cyr2lat_char_map exists, create a profile from it
+          (json['cyr2lat_char_map'] != null
+              ? [
+                  Cyr2LatProfile(
+                    id: 'migrated',
+                    name: 'Migrated Profile',
+                    charMap:
+                        (json['cyr2lat_char_map'] as Map?)?.map(
+                          (key, value) =>
+                              MapEntry(key.toString(), value.toString()),
+                        ) ??
+                        defaultCyr2LatCharMap,
+                  ),
+                ]
+              : [
+                  Cyr2LatProfile(
+                    id: 'default',
+                    name: 'Default',
+                    charMap: defaultCyr2LatCharMap,
+                  ),
+                ]),
+      selectedCyr2latProfileId:
+          json['selected_cyr2lat_profile_id'] as String? ??
+          (json['cyr2lat_char_map'] != null ? 'migrated' : 'default'),
    );
  }

@@ -109,10 +369,13 @@ class AppSettings {
    bool? mapShowRepeaters,
    bool? mapShowChatNodes,
    bool? mapShowOtherNodes,
+    bool? mapShowOverlaps,
    double? mapTimeFilterHours,
    bool? mapKeyPrefixEnabled,
    String? mapKeyPrefix,
    bool? mapShowMarkers,
+    bool? mapShowGuessedLocations,
+    bool? enableMessageTracing,
    Object? mapCacheBounds = _unset,
    int? mapCacheMinZoom,
    int? mapCacheMaxZoom,
@@ -121,20 +384,45 @@ class AppSettings {
    bool? notifyOnNewChannelMessage,
    bool? notifyOnNewAdvert,
    bool? autoRouteRotationEnabled,
+    double? maxRouteWeight,
+    double? initialRouteWeight,
+    double? routeWeightSuccessIncrement,
+    double? routeWeightFailureDecrement,
+    int? maxMessageRetries,
    String? themeMode,
    Object? languageOverride = _unset,
    bool? appDebugLogEnabled,
    Map<String, String>? batteryChemistryByDeviceId,
+    Map<String, String>? batteryChemistryByRepeaterId,
+    UnitSystem? unitSystem,
+    Set<String>? mutedChannels,
+    bool? mapShowDiscoveryContacts,
+    String? tcpServerAddress,
+    int? tcpServerPort,
+    bool? jumpToOldestUnread,
+    bool? translationEnabled,
+    bool? autoTranslateIncomingMessages,
+    Object? translationTargetLanguageCode = _unset,
+    bool? composerTranslationEnabled,
+    Object? translationModelSourceUrl = _unset,
+    Object? translationSelectedModelId = _unset,
+    List<TranslationModelRecord>? translationDownloadedModels,
+    List<Cyr2LatProfile>? cyr2latProfiles,
+    String? selectedCyr2latProfileId,
  }) {
    return AppSettings(
      clearPathOnMaxRetry: clearPathOnMaxRetry ?? this.clearPathOnMaxRetry,
      mapShowRepeaters: mapShowRepeaters ?? this.mapShowRepeaters,
      mapShowChatNodes: mapShowChatNodes ?? this.mapShowChatNodes,
      mapShowOtherNodes: mapShowOtherNodes ?? this.mapShowOtherNodes,
+      mapShowOverlaps: mapShowOverlaps ?? this.mapShowOverlaps,
      mapTimeFilterHours: mapTimeFilterHours ?? this.mapTimeFilterHours,
      mapKeyPrefixEnabled: mapKeyPrefixEnabled ?? this.mapKeyPrefixEnabled,
      mapKeyPrefix: mapKeyPrefix ?? this.mapKeyPrefix,
      mapShowMarkers: mapShowMarkers ?? this.mapShowMarkers,
+      mapShowGuessedLocations:
+          mapShowGuessedLocations ?? this.mapShowGuessedLocations,
+      enableMessageTracing: enableMessageTracing ?? this.enableMessageTracing,
      mapCacheBounds: mapCacheBounds == _unset
          ? this.mapCacheBounds
          : mapCacheBounds as Map<String, double>?,
@@ -147,6 +435,13 @@ class AppSettings {
      notifyOnNewAdvert: notifyOnNewAdvert ?? this.notifyOnNewAdvert,
      autoRouteRotationEnabled:
          autoRouteRotationEnabled ?? this.autoRouteRotationEnabled,
+      maxRouteWeight: maxRouteWeight ?? this.maxRouteWeight,
+      initialRouteWeight: initialRouteWeight ?? this.initialRouteWeight,
+      routeWeightSuccessIncrement:
+          routeWeightSuccessIncrement ?? this.routeWeightSuccessIncrement,
+      routeWeightFailureDecrement:
+          routeWeightFailureDecrement ?? this.routeWeightFailureDecrement,
+      maxMessageRetries: maxMessageRetries ?? this.maxMessageRetries,
      themeMode: themeMode ?? this.themeMode,
      languageOverride: languageOverride == _unset
          ? this.languageOverride
@@ -154,6 +449,34 @@ class AppSettings {
      appDebugLogEnabled: appDebugLogEnabled ?? this.appDebugLogEnabled,
      batteryChemistryByDeviceId:
          batteryChemistryByDeviceId ?? this.batteryChemistryByDeviceId,
+      batteryChemistryByRepeaterId:
+          batteryChemistryByRepeaterId ?? this.batteryChemistryByRepeaterId,
+      unitSystem: unitSystem ?? this.unitSystem,
+      mutedChannels: mutedChannels ?? this.mutedChannels,
+      mapShowDiscoveryContacts:
+          mapShowDiscoveryContacts ?? this.mapShowDiscoveryContacts,
+      tcpServerAddress: tcpServerAddress ?? this.tcpServerAddress,
+      tcpServerPort: tcpServerPort ?? this.tcpServerPort,
+      jumpToOldestUnread: jumpToOldestUnread ?? this.jumpToOldestUnread,
+      translationEnabled: translationEnabled ?? this.translationEnabled,
+      autoTranslateIncomingMessages:
+          autoTranslateIncomingMessages ?? this.autoTranslateIncomingMessages,
+      translationTargetLanguageCode: translationTargetLanguageCode == _unset
+          ? this.translationTargetLanguageCode
+          : translationTargetLanguageCode as String?,
+      composerTranslationEnabled:
+          composerTranslationEnabled ?? this.composerTranslationEnabled,
+      translationModelSourceUrl: translationModelSourceUrl == _unset
+          ? this.translationModelSourceUrl
+          : translationModelSourceUrl as String?,
+      translationSelectedModelId: translationSelectedModelId == _unset
+          ? this.translationSelectedModelId
+          : translationSelectedModelId as String?,
+      translationDownloadedModels:
+          translationDownloadedModels ?? this.translationDownloadedModels,
+      cyr2latProfiles: cyr2latProfiles ?? this.cyr2latProfiles,
+      selectedCyr2latProfileId:
+          selectedCyr2latProfileId ?? this.selectedCyr2latProfileId,
    );
  }
 }
@@ -4,6 +4,9 @@ import 'dart:typed_data';
 import 'package:crypto/crypto.dart' as crypto;

 import '../connector/meshcore_protocol.dart';
+import 'community.dart';
+
+enum ChannelType { public, private, hashtag, communityPublic, communityHashtag }

 class Channel {
  final int index;
@@ -24,20 +27,23 @@ class Channel {

  bool get isPublicChannel => pskHex == publicChannelPsk;

-  static Channel? fromFrame(Uint8List data) {
+  static Channel? fromFrame(Uint8List frame) {
    // CHANNEL_INFO format:
    // [0] = RESP_CODE_CHANNEL_INFO (18)
    // [1] = channel_idx
    // [2-33] = name (32 bytes, null-terminated)
    // [34-49] = psk (16 bytes)
-    if (data.length < 50) return null;
-    if (data[0] != respCodeChannelInfo) return null;
-
-    final index = data[1];
-    final name = readCString(data, 2, 32);
-    final psk = Uint8List.fromList(data.sublist(34, 50));
-
-    return Channel(index: index, name: name, psk: psk);
+    if (frame.length < 50) return null;
+    final reader = BufferReader(frame);
+    try {
+      if (reader.readByte() != respCodeChannelInfo) return null;
+      final index = reader.readByte();
+      final name = reader.readCStringGreedy(32);
+      final psk = reader.readBytes(16);
+      return Channel(index: index, name: name, psk: psk);
+    } catch (e) {
+      return null;
+    }
  }

  static Channel empty(int index) {
@@ -108,5 +114,36 @@ class Channel {
    return bytes.map((b) => b.toRadixString(16).padLeft(2, '0')).join();
  }

+  static bool isCommunityChannel(ChannelType channelType) {
+    switch (channelType) {
+      case ChannelType.communityPublic:
+      case ChannelType.communityHashtag:
+        return true;
+      case ChannelType.public:
+      case ChannelType.private:
+      case ChannelType.hashtag:
+        return false;
+    }
+  }
+
+  static ChannelType getChannelType(
+    Channel channel,
+    CommunityPskIndex communityIndex,
+  ) {
+    Community? community = communityIndex.getCommunityForChannel(channel);
+    if (community != null) {
+      if (Community.isCommunityPublicChannel(channel, community)) {
+        return ChannelType.communityPublic;
+      }
+      return ChannelType.communityHashtag;
+    }
+    if (channel.isPublicChannel) {
+      return ChannelType.public;
+    } else if (channel.name.startsWith('#')) {
+      return ChannelType.hashtag;
+    }
+    return ChannelType.private;
+  }
+
  static const String publicChannelPsk = '8b3387e9c5cdea6ac9e5edbaa115cd72';
 }
@@ -2,6 +2,8 @@ import 'dart:typed_data';
 import '../connector/meshcore_protocol.dart';
 import '../helpers/reaction_helper.dart';
 import '../helpers/smaz.dart';
+import 'translation_support.dart';
+import '../utils/app_logger.dart';

 enum ChannelMessageStatus { pending, sent, failed }

@@ -23,9 +25,16 @@ class Repeat {
 }

 class ChannelMessage {
+  static const Object _unset = Object();
+
  final Uint8List? senderKey;
  final String senderName;
  final String text;
+  final String? originalText;
+  final String? translatedText;
+  final String? translatedLanguageCode;
+  final MessageTranslationStatus translationStatus;
+  final String? translationModelId;
  final DateTime timestamp;
  final bool isOutgoing;
  final ChannelMessageStatus status;
@@ -36,6 +45,7 @@ class ChannelMessage {
  final List<Uint8List> pathVariants;
  final int? channelIndex;
  final String messageId;
+  final String? packetHash;
  final String? replyToMessageId;
  final String? replyToSenderName;
  final String? replyToText;
@@ -45,6 +55,11 @@ class ChannelMessage {
    this.senderKey,
    required this.senderName,
    required this.text,
+    this.originalText,
+    this.translatedText,
+    this.translatedLanguageCode,
+    this.translationStatus = MessageTranslationStatus.none,
+    this.translationModelId,
    required this.timestamp,
    required this.isOutgoing,
    this.status = ChannelMessageStatus.pending,
@@ -55,6 +70,7 @@ class ChannelMessage {
    List<Uint8List>? pathVariants,
    this.channelIndex,
    String? messageId,
+    this.packetHash,
    this.replyToMessageId,
    this.replyToSenderName,
    this.replyToText,
@@ -79,15 +95,34 @@ class ChannelMessage {
    int? pathLength,
    Uint8List? pathBytes,
    List<Uint8List>? pathVariants,
+    String? packetHash,
    String? replyToMessageId,
    String? replyToSenderName,
    String? replyToText,
+    Object? originalText = _unset,
+    Object? translatedText = _unset,
+    Object? translatedLanguageCode = _unset,
+    MessageTranslationStatus? translationStatus,
+    Object? translationModelId = _unset,
    Map<String, int>? reactions,
  }) {
    return ChannelMessage(
      senderKey: senderKey,
      senderName: senderName,
      text: text,
+      originalText: originalText == _unset
+          ? this.originalText
+          : originalText as String?,
+      translatedText: translatedText == _unset
+          ? this.translatedText
+          : translatedText as String?,
+      translatedLanguageCode: translatedLanguageCode == _unset
+          ? this.translatedLanguageCode
+          : translatedLanguageCode as String?,
+      translationStatus: translationStatus ?? this.translationStatus,
+      translationModelId: translationModelId == _unset
+          ? this.translationModelId
+          : translationModelId as String?,
      timestamp: timestamp,
      isOutgoing: isOutgoing,
      status: status ?? this.status,
@@ -98,6 +133,7 @@ class ChannelMessage {
      pathVariants: pathVariants ?? this.pathVariants,
      channelIndex: channelIndex,
      messageId: messageId,
+      packetHash: packetHash ?? this.packetHash,
      replyToMessageId: replyToMessageId ?? this.replyToMessageId,
      replyToSenderName: replyToSenderName ?? this.replyToSenderName,
      replyToText: replyToText ?? this.replyToText,
@@ -105,100 +141,99 @@ class ChannelMessage {
    );
  }

-  static ChannelMessage? fromFrame(Uint8List data) {
+  static ChannelMessage? fromFrame(Uint8List frame) {
    // CHANNEL_MSG_RECV format varies by version:
    // V3: [0]=code [1]=SNR [2]=rsv1 [3]=rsv2 [4]=channel_idx [5]=path_len [path... optional] [txt_type] [timestamp x4] [text...]
    // Non-V3: [0]=code [1]=channel_idx [2]=path_len [3]=txt_type [4-7]=timestamp [8+]=text
-    if (data.length < 8) return null;
+    if (frame.length < 8) return null;
+    try {
+      final reader = BufferReader(frame);
+      final code = reader.readByte();
+      if (code != respCodeChannelMsgRecv && code != respCodeChannelMsgRecvV3) {
+        return null;
+      }

-    final code = data[0];
-    if (code != respCodeChannelMsgRecv && code != respCodeChannelMsgRecvV3) {
+      int pathLen;
+      int txtType;
+      Uint8List pathBytes = Uint8List(0);
+      int channelIdx;
+      if (code == respCodeChannelMsgRecvV3) {
+        reader.skipBytes(1); // Skip SNR
+        final flags = reader.readByte();
+        final hasPath = (flags & 0x01) != 0;
+        reader.skipBytes(1); // Skip reserved byte
+        channelIdx = reader.readByte();
+        pathLen = reader.readInt8();
+        txtType = reader.readByte();
+        if (hasPath && pathLen > 0) {
+          reader.rewind(); // Rewind to read path length again for pathBytes
+          pathBytes = reader.readBytes(pathLen);
+        }
+      } else {
+        channelIdx = reader.readByte();
+        pathLen = reader.readInt8();
+        txtType = reader.readByte();
+      }
+      final timestampRaw = reader.readUInt32LE();
+
+      if (txtType != txtTypePlain) {
+        return null;
+      }
+
+      final text = reader.readCString();
+
+      // Extract sender name and actual message from "name: msg" format
+      String senderName = 'Unknown';
+      String actualText = text;
+
+      final colonIndex = text.indexOf(':');
+      if (colonIndex > 0 && colonIndex < text.length - 1 && colonIndex < 50) {
+        final potentialSender = text.substring(0, colonIndex);
+        if (!RegExp(r'[:\[\]]').hasMatch(potentialSender)) {
+          senderName = potentialSender;
+          final offset =
+              (colonIndex + 1 < text.length && text[colonIndex + 1] == ' ')
+              ? colonIndex + 2
+              : colonIndex + 1;
+          actualText = text.substring(offset);
+        }
+      }
+
+      final decodedText = Smaz.tryDecodePrefixed(actualText) ?? actualText;
+
+      return ChannelMessage(
+        senderKey: null,
+        senderName: senderName,
+        text: decodedText,
+        timestamp: DateTime.fromMillisecondsSinceEpoch(timestampRaw * 1000),
+        isOutgoing: false,
+        status: ChannelMessageStatus.sent,
+        pathLength: pathLen,
+        pathBytes: pathBytes,
+        channelIndex: channelIdx,
+      );
+    } catch (e) {
+      appLogger.error('Error parsing channel message frame: $e');
+      // If parsing fails, return null to avoid crashes
      return null;
    }
-
-    int timestampOffset, textOffset, pathLenOffset, txtTypeOffset;
-    Uint8List pathBytes = Uint8List(0);
-    int channelIdx;
-
-    if (code == respCodeChannelMsgRecvV3) {
-      channelIdx = data[4];
-      pathLenOffset = 5;
-      final pathLen = data[pathLenOffset].toSigned(8);
-      var cursor = 6;
-      final hasPathBytesFlag = (data[2] & 0x01) != 0;
-      final canFitPath = pathLen > 0 && data.length >= cursor + pathLen + 5;
-      final hasValidTxtType =
-          cursor < data.length &&
-          (data[cursor] == txtTypePlain || data[cursor] == txtTypeCliData);
-      if ((hasPathBytesFlag || (canFitPath && !hasValidTxtType)) &&
-          canFitPath) {
-        pathBytes = Uint8List.fromList(data.sublist(cursor, cursor + pathLen));
-        cursor += pathLen;
-      }
-      txtTypeOffset = cursor;
-      cursor += 1; // txt_type
-      timestampOffset = cursor;
-      textOffset = cursor + 4;
-    } else {
-      channelIdx = data[1];
-      pathLenOffset = 2;
-      txtTypeOffset = 3;
-      timestampOffset = 4;
-      textOffset = 8;
-    }
-
-    if (data.length < textOffset + 1) return null;
-
-    final txtType = data[txtTypeOffset];
-    if (txtType != txtTypePlain) {
-      return null;
-    }
-
-    final pathLen = data[pathLenOffset].toSigned(8);
-    final timestampRaw = readUint32LE(data, timestampOffset);
-    final text = readCString(data, textOffset, data.length - textOffset);
-
-    // Extract sender name and actual message from "name: msg" format
-    String senderName = 'Unknown';
-    String actualText = text;
-
-    final colonIndex = text.indexOf(':');
-    if (colonIndex > 0 && colonIndex < text.length - 1 && colonIndex < 50) {
-      final potentialSender = text.substring(0, colonIndex);
-      if (!RegExp(r'[:\[\]]').hasMatch(potentialSender)) {
-        senderName = potentialSender;
-        final offset =
-            (colonIndex + 1 < text.length && text[colonIndex + 1] == ' ')
-            ? colonIndex + 2
-            : colonIndex + 1;
-        actualText = text.substring(offset);
-      }
-    }
-
-    final decodedText = Smaz.tryDecodePrefixed(actualText) ?? actualText;
-
-    return ChannelMessage(
-      senderKey: null,
-      senderName: senderName,
-      text: decodedText,
-      timestamp: DateTime.fromMillisecondsSinceEpoch(timestampRaw * 1000),
-      isOutgoing: false,
-      status: ChannelMessageStatus.sent,
-      pathLength: pathLen,
-      pathBytes: pathBytes,
-      channelIndex: channelIdx,
-    );
  }

  static ChannelMessage outgoing(
    String text,
    String senderName,
-    int channelIndex,
-  ) {
+    int channelIndex, {
+    String? originalText,
+    String? translatedLanguageCode,
+    String? translationModelId,
+  }) {
    return ChannelMessage(
      senderKey: null,
      senderName: senderName,
      text: text,
+      originalText: originalText,
+      translatedLanguageCode: translatedLanguageCode,
+      translationModelId: translationModelId,
      timestamp: DateTime.now(),
      isOutgoing: true,
      status: ChannelMessageStatus.pending,
@@ -4,6 +4,8 @@ import 'dart:typed_data';

 import 'package:crypto/crypto.dart' as crypto;

+import 'channel.dart';
+
 /// Represents a community with a shared secret for deriving channel PSKs.
 ///
 /// A Community is a namespace with a shared secret K (32 random bytes),
@@ -162,6 +164,12 @@ class Community {
    return hashtag.replaceFirst(RegExp(r'^#'), '').toLowerCase().trim();
  }

+  /// Returns true if this is the community's public channel
+  static bool isCommunityPublicChannel(Channel channel, Community community) {
+    final publicPsk = community.deriveCommunityPublicPsk();
+    return channel.pskHex == Channel.formatPskHex(publicPsk);
+  }
+
  /// Add a hashtag channel to this community's list
  Community addHashtagChannel(String hashtag) {
    final normalized = _normalizeCommunityHashtag(hashtag);
@@ -237,3 +245,28 @@ class Community {
  @override
  int get hashCode => id.hashCode;
 }
+
+class CommunityPskIndex {
+  // Cache of PSK hex -> Community for quick lookup
+  final Map<String, Community> _pskToCommunity = {};
+
+  void initialize(List<Community> communities) {
+    _pskToCommunity.clear();
+    for (final community in communities) {
+      // Map the community public channel PSK
+      final publicPsk = community.deriveCommunityPublicPsk();
+      _pskToCommunity[Channel.formatPskHex(publicPsk)] = community;
+
+      // Map all known hashtag channel PSKs
+      for (final hashtag in community.hashtagChannels) {
+        final hashtagPsk = community.deriveCommunityHashtagPsk(hashtag);
+        _pskToCommunity[Channel.formatPskHex(hashtagPsk)] = community;
+      }
+    }
+  }
+
+  /// Returns the community this channel belongs to, or null if not a community channel
+  Community? getCommunityForChannel(Channel channel) {
+    return _pskToCommunity[channel.pskHex];
+  }
+}
@@ -0,0 +1,48 @@
+import 'dart:typed_data';
+
+import '../connector/meshcore_protocol.dart';
+import '../utils/app_logger.dart';
+
+/// Parsed `RESP_CODE_STATS` + `STATS_TYPE_RADIO` (14 bytes total).
+class CompanionRadioStats {
+  final int noiseFloorDbm;
+  final int lastRssiDbm;
+  final double lastSnrDb;
+  final int txAirSecs;
+  final int rxAirSecs;
+  final DateTime receivedAt;
+
+  const CompanionRadioStats({
+    required this.noiseFloorDbm,
+    required this.lastRssiDbm,
+    required this.lastSnrDb,
+    required this.txAirSecs,
+    required this.rxAirSecs,
+    required this.receivedAt,
+  });
+
+  static CompanionRadioStats? tryParse(Uint8List frame) {
+    if (frame.length < 14) return null;
+    if (frame[0] != respCodeStats || frame[1] != statsTypeRadio) return null;
+    try {
+      final reader = BufferReader(frame);
+      reader.skipBytes(2);
+      final noise = reader.readInt16LE();
+      final rssi = reader.readInt8();
+      final snrRaw = reader.readInt8();
+      final txAir = reader.readUInt32LE();
+      final rxAir = reader.readUInt32LE();
+      return CompanionRadioStats(
+        noiseFloorDbm: noise,
+        lastRssiDbm: rssi,
+        lastSnrDb: snrRaw / 4.0,
+        txAirSecs: txAir,
+        rxAirSecs: rxAir,
+        receivedAt: DateTime.now(),
+      );
+    } catch (e) {
+      appLogger.warn('CompanionRadioStats parse error: $e');
+      return null;
+    }
+  }
+}
@@ -1,10 +1,13 @@
 import 'dart:typed_data';
+import 'package:meshcore_open/utils/app_logger.dart';
+
 import '../connector/meshcore_protocol.dart';

 class Contact {
  final Uint8List publicKey;
  final String name;
  final int type;
+  final int flags;
  final int pathLength; // -1 = flood, 0+ = direct hops (from device)
  final Uint8List path; // Path bytes from device
  final int?
@@ -14,11 +17,16 @@ class Contact {
  final double? longitude;
  final DateTime lastSeen;
  final DateTime lastMessageAt;
+  final DateTime? lastModified;
+  final bool isActive;
+  final bool wasPulled;
+  final Uint8List? rawPacket;

  Contact({
    required this.publicKey,
    required this.name,
    required this.type,
+    this.flags = 0,
    required this.pathLength,
    required this.path,
    this.pathOverride,
@@ -26,12 +34,19 @@ class Contact {
    this.latitude,
    this.longitude,
    required this.lastSeen,
+    this.lastModified,
    DateTime? lastMessageAt,
+    this.isActive = true,
+    this.wasPulled = false,
+    this.rawPacket,
  }) : lastMessageAt = lastMessageAt ?? lastSeen;

  String get publicKeyHex => pubKeyToHex(publicKey);

-  String get typeLabel {
+  /// Non-localized type label, intended for logs and non-UI exports
+  /// (e.g. GPX). For UI use the `typeLabel(l10n)` extension in
+  /// `lib/l10n/contact_localization.dart`.
+  String get typeLabelRaw {
    switch (type) {
      case advTypeChat:
        return 'Chat';
@@ -46,23 +61,24 @@ class Contact {
    }
  }

-  String get pathLabel {
-    if (pathOverride != null) {
-      if (pathOverride! < 0) return 'Flood (forced)';
-      if (pathOverride == 0) return 'Direct (forced)';
-      return '$pathOverride hops (forced)';
-    }
-    if (pathLength < 0) return 'Flood';
-    if (pathLength == 0) return 'Direct';
-    return '$pathLength hops';
+  bool get hasLocation {
+    const double epsilon = 1e-6;
+    final lat = latitude ?? 0.0;
+    final lon = longitude ?? 0.0;
+    return (lat.abs() > epsilon || lon.abs() > epsilon) &&
+        lat >= -90.0 &&
+        lat <= 90.0 &&
+        lon >= -180.0 &&
+        lon <= 180.0;
  }

-  bool get hasLocation => latitude != null && longitude != null;
+  bool get isFavorite => (flags & contactFlagFavorite) != 0;

  Contact copyWith({
    Uint8List? publicKey,
    String? name,
    int? type,
+    int? flags,
    int? pathLength,
    Uint8List? path,
    int? pathOverride,
@@ -72,11 +88,15 @@ class Contact {
    double? longitude,
    DateTime? lastSeen,
    DateTime? lastMessageAt,
+    DateTime? lastModified,
+    bool? isActive,
+    Uint8List? rawPacket,
  }) {
    return Contact(
      publicKey: publicKey ?? this.publicKey,
      name: name ?? this.name,
      type: type ?? this.type,
+      flags: flags ?? this.flags,
      pathLength: pathLength ?? this.pathLength,
      path: path ?? this.path,
      pathOverride: clearPathOverride
@@ -89,18 +109,20 @@ class Contact {
      longitude: longitude ?? this.longitude,
      lastSeen: lastSeen ?? this.lastSeen,
      lastMessageAt: lastMessageAt ?? this.lastMessageAt,
+      lastModified: lastModified ?? this.lastModified,
+      isActive: isActive ?? this.isActive,
+      rawPacket: rawPacket ?? this.rawPacket,
    );
  }

-  String get pathIdList {
-    final pathBytes = _pathBytesForDisplay;
+  /// Formats path bytes into comma-separated hex groups of [hashByteWidth] bytes.
+  String pathFormattedIdList(int hashByteWidth) {
+    final pathBytes = pathBytesForDisplay;
    if (pathBytes.isEmpty) return '';
+    final w = hashByteWidth.clamp(1, 8);
    final parts = <String>[];
-    final groupSize = pathHashSize;
-    for (int i = 0; i < pathBytes.length; i += groupSize) {
-      final end = (i + groupSize) <= pathBytes.length
-          ? (i + groupSize)
-          : pathBytes.length;
+    for (int i = 0; i < pathBytes.length; i += w) {
+      final end = (i + w) <= pathBytes.length ? (i + w) : pathBytes.length;
      final chunk = pathBytes.sublist(i, end);
      parts.add(
        chunk
@@ -111,47 +133,14 @@ class Contact {
    return parts.join(',');
  }

+  /// Default grouping uses legacy single-byte hop hash width.
+  String get pathIdList => pathFormattedIdList(pathHashSize);
+
  String get shortPubKeyHex {
    return "<${publicKeyHex.substring(0, 8)}...${publicKeyHex.substring(publicKeyHex.length - 8)}>";
  }

-  Uint8List? get traceRouteBytes {
-    final pathBytes = _pathBytesForDisplay;
-    Uint8List? traceBytes;
-
-    if (pathLength <= 0) {
-      traceBytes = Uint8List(1);
-      traceBytes[0] = publicKey[0];
-      return traceBytes;
-    }
-
-    if (type == advTypeRepeater || type == advTypeRoom) {
-      final len = (pathBytes.length + pathBytes.length + 1);
-      traceBytes = Uint8List(len);
-      traceBytes[pathBytes.length] = publicKey[0];
-      for (int i = 0; i < pathBytes.length; i++) {
-        traceBytes[i] = pathBytes[i];
-        if (i < pathBytes.length) {
-          traceBytes[len - 1 - i] = pathBytes[i];
-        }
-      }
-    } else {
-      if (pathBytes.length < 2) {
-        return pathBytes[0] == 0 ? null : pathBytes;
-      }
-      final len = (pathBytes.length + pathBytes.length - 1);
-      traceBytes = Uint8List(len);
-      for (int i = 0; i < pathBytes.length; i++) {
-        traceBytes[i] = pathBytes[i];
-        if (i < pathBytes.length - 1) {
-          traceBytes[len - 1 - i] = pathBytes[i];
-        }
-      }
-    }
-    return traceBytes;
-  }
-
-  Uint8List get _pathBytesForDisplay {
+  Uint8List get pathBytesForDisplay {
    if (pathOverride != null) {
      if (pathOverride! < 0) return Uint8List(0);
      return pathOverrideBytes ?? Uint8List(0);
@@ -160,43 +149,85 @@ class Contact {
  }

  static Contact? fromFrame(Uint8List data) {
-    if (data.length < contactFrameSize) return null;
-    if (data[0] != respCodeContact) return null;
+    if (data.isEmpty) return null;
+    final reader = BufferReader(data);
+    try {
+      final respCode = reader.readByte();
+      if (respCode != respCodeContact && respCode != pushCodeNewAdvert) {
+        return null;
+      }
+      final pubKey = reader.readBytes(pubKeySize);

-    final pubKey = Uint8List.fromList(
-      data.sublist(contactPubKeyOffset, contactPubKeyOffset + pubKeySize),
-    );
-    final type = data[contactTypeOffset];
-    final pathLen = data[contactPathLenOffset].toSigned(8);
-    final safePathLen = pathLen > 0
-        ? (pathLen > maxPathSize ? maxPathSize : pathLen)
-        : 0;
-    final pathBytes = safePathLen > 0
-        ? Uint8List.fromList(
-            data.sublist(contactPathOffset, contactPathOffset + safePathLen),
-          )
-        : Uint8List(0);
-    final name = readCString(data, contactNameOffset, maxNameSize);
-    final lastmod = readUint32LE(data, contactLastmodOffset);
+      // Guard: reject contacts with zeroed or mostly-zeroed public keys
+      // (indicates corrupt flash storage on the firmware side)
+      final zeroCount = pubKey.where((b) => b == 0).length;
+      if (zeroCount > pubKeySize ~/ 2) return null;

-    double? lat, lon;
-    final latRaw = readInt32LE(data, contactLatOffset);
-    final lonRaw = readInt32LE(data, contactLonOffset);
-    if (latRaw != 0 || lonRaw != 0) {
-      lat = latRaw / 1e6;
-      lon = lonRaw / 1e6;
+      final type = reader.readByte();
+      final flags = reader.readByte();
+      final pathLen = reader.readByte();
+      final safePathLen = pathLen > 0
+          ? (pathLen > maxPathSize ? maxPathSize : pathLen)
+          : 0;
+      final pathBytes = reader.readBytes(maxPathSize).sublist(0, safePathLen);
+      final name = reader.readCStringGreedy(maxNameSize);
+
+      // Guard: reject contacts with non-printable names (corrupt flash data)
+      if (name.isNotEmpty &&
+          name.codeUnits.every((c) => c < 0x20 || c == 0xFFFD)) {
+        return null;
+      }
+
+      // mandatory last_advert_timestamp
+      final lastAdvertTimestamp = reader.readUInt32LE();
+
+      double? lat, lon;
+      DateTime? lastModified;
+      if (reader.remaining >= 12) {
+        final latRaw = reader.readInt32LE();
+        final lonRaw = reader.readInt32LE();
+        final lastModRaw = reader.readUInt32LE();
+        // TODO: should this be &&?
+        if (latRaw != 0 || lonRaw != 0) {
+          lat = latRaw / 1e6;
+          lon = lonRaw / 1e6;
+        }
+        if (lastModRaw != 0) {
+          lastModified = DateTime.fromMillisecondsSinceEpoch(lastModRaw * 1000);
+        }
+      } else if (reader.remaining >= 8) {
+        // Old layout: gps without lastmod
+        final latRaw = reader.readInt32LE();
+        final lonRaw = reader.readInt32LE();
+        if (latRaw != 0 || lonRaw != 0) {
+          lat = latRaw / 1e6;
+          lon = lonRaw / 1e6;
+        }
+        appLogger.info(
+          'Contact ${pubKeyToHex(pubKey).substring(0, 8)} has gps but no lastmod (legacy firmware layout)',
+        );
+      }
+
+      return Contact(
+        publicKey: pubKey,
+        name: name.isEmpty ? 'Unknown' : name,
+        type: type,
+        flags: flags,
+        pathLength: (pathLen == 0xFF || pathLen > maxPathSize) ? -1 : pathLen,
+        path: pathBytes,
+        latitude: lat,
+        longitude: lon,
+        lastSeen: DateTime.fromMillisecondsSinceEpoch(
+          lastAdvertTimestamp * 1000,
+        ),
+        lastModified: lastModified,
+        isActive: true,
+        rawPacket: null,
+      );
+    } catch (e) {
+      appLogger.error('Failed to parse contact frame: $e');
+      return null;
    }
-
-    return Contact(
-      publicKey: pubKey,
-      name: name.isEmpty ? 'Unknown' : name,
-      type: type,
-      pathLength: pathLen,
-      path: pathBytes,
-      latitude: lat,
-      longitude: lon,
-      lastSeen: DateTime.fromMillisecondsSinceEpoch(lastmod * 1000),
-    );
  }

  @override
@@ -205,4 +236,7 @@ class Contact {

  @override
  int get hashCode => publicKeyHex.hashCode;
+  bool get teleBaseEnabled => (flags & contactFlagTeleBase) != 0;
+  bool get teleLocEnabled => (flags & contactFlagTeleLoc) != 0;
+  bool get teleEnvEnabled => (flags & contactFlagTeleEnv) != 0;
 }
@@ -0,0 +1,43 @@
+class DeliveryObservation {
+  final String contactKey;
+  final int pathLength;
+  final int messageBytes;
+  final int secondsSinceLastRx;
+  final bool isFlood;
+  final int deliveryMs;
+  final DateTime timestamp;
+
+  DeliveryObservation({
+    required this.contactKey,
+    required this.pathLength,
+    required this.messageBytes,
+    required this.secondsSinceLastRx,
+    required this.isFlood,
+    required this.deliveryMs,
+    required this.timestamp,
+  });
+
+  Map<String, dynamic> toJson() {
+    return {
+      'contact_key': contactKey,
+      'path_length': pathLength,
+      'message_bytes': messageBytes,
+      'seconds_since_last_rx': secondsSinceLastRx,
+      'is_flood': isFlood,
+      'delivery_ms': deliveryMs,
+      'timestamp': timestamp.toIso8601String(),
+    };
+  }
+
+  factory DeliveryObservation.fromJson(Map<String, dynamic> json) {
+    return DeliveryObservation(
+      contactKey: json['contact_key'] as String,
+      pathLength: json['path_length'] as int,
+      messageBytes: json['message_bytes'] as int,
+      secondsSinceLastRx: json['seconds_since_last_rx'] as int? ?? 0,
+      isFlood: json['is_flood'] as bool,
+      deliveryMs: json['delivery_ms'] as int,
+      timestamp: DateTime.parse(json['timestamp'] as String),
+    );
+  }
+}
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#e3e3e3"><path d="M268-240 42-466l57-56 170 170 56 56-57 56Zm226 0L268-466l56-57 170 170 368-368 56 57-424 424Zm0-226-57-56 198-198 57 56-198 198Z"/></svg>`