Files
zjs81 462159e803 Tester feedback: offline mode, pt-PT, menus, layout and translations
Offline (read-only) mode
- The last connected radio is remembered; with no radio the app opens on
  its saved contacts, channels, messages and unread counts.
- Main screens stay open on disconnect. A Connect button replaces the
  battery and signal indicators, with a sheet to reconnect, choose a
  radio or stop a pending reconnect.
- While disconnected everything is read-only: the composer becomes a
  "connect to send" bar (drafts kept) and controls that change the radio
  or stored history are disabled or hidden.
- Resending while disconnected no longer deletes the message; a
  different radio no longer shows the previous radio's channels.
- Notification taps open the saved chat while offline.

Chats and menus
- Channel chat menu: notifications, edit channel, delete channel; the
  filter row lines up with the others; bell moved out of the app bar.
- DM and room menus: remove from contacts; rooms get room management.
- Search field uses the full app bar; long-press a result to copy.
- Hashtag channel titles no longer read "# #name"; more room around the
  radio activity dot.
- Repeat filter: short messages from one sender are caught at the same
  count as long ones.

Layout
- Shared menu row (wraps to two lines) and segment label (never splits
  a word) used across the app.
- One Scan button on the scanner; consistent settings tile titles;
  contact "last seen" wraps instead of truncating; unfetched repeater
  settings are dimmed.

Localization
- New European Portuguese locale (pt_PT); regional locales are handled
  by the language picker, notifications and the background service.
- Fill 67 missing strings per locale, including backup and restore.
- Keep "Flood" and "Zero Hop" untranslated, shorten "last seen" and
  routing labels, and fix mistranslated scan, theme and hop strings.
- Received-image strings, badge and caption come from translations.
- Regenerate the Czech localizations, which were missing strings.

Docs
- Add documentation/design.md (UI reference) and offline-mode.md;
  update channel, chat, navigation and scanner docs.
2026-11-09 21:18:29 -07:00

43 lines
5.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Repository Guidelines
## Project Structure & Module Organization
- Core Flutter code is in `lib/`, with BLE protocol definitions in `lib/connector/meshcore_protocol.dart` and BLE transport/state in `lib/connector/meshcore_connector.dart`.
- UI lives in `lib/screens/` and `lib/widgets/`, models in `lib/models/`, tests in `test/`, and platform runners in `android/`, `ios/`, `macos/`, `linux/`, `windows/`, `web/`.
## 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 the Nordic UART Service UUID; known name prefixes are reference values, not filters.
- 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, `cmdGetStats`=56, `cmdSendAnonReq`=57, `cmdSetAutoAddConfig`=58, `cmdGetAutoAddConfig`=59, `cmdSetPathHashMode`=61, `cmdSendChannelData`=62.
- 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, `respCodeStats`=24, `respCodeAutoAddConfig`=25, `respCodeChannelDataRecv`=27.
- Push codes (async): `pushCodeAdvert`=0x80, `pushCodePathUpdated`=0x81, `pushCodeSendConfirmed`=0x82, `pushCodeMsgWaiting`=0x83, `pushCodeLoginSuccess`=0x85, `pushCodeLoginFail`=0x86, `pushCodeLogRxData`=0x88, `pushCodeNewAdvert`=0x8A.
- Device info: `cmdAppStart` triggers `respCodeSelfInfo` with tx power, pubkey, lat/lon, telemetry flags, radio params, and node name (see offsets in `lib/connector/meshcore_connector.dart`).
- Radio/time helpers: radio settings come from self-info; companion stats use `cmdGetStats` → `respCodeStats`; `cmdGetDeviceTime` → `respCodeCurrTime`; `cmdSetDeviceTime` updates device time.
- Reboot: companion Settings calls `rebootDevice()` → `buildRebootFrame()`; remote repeater management uses CLI `reboot`.
- Companion radio format: `cmdSendTxtMsg` expects `[cmd][txt_type][attempt][timestamp x4][pub_key_prefix x6][text...]` (no flags/full pubkey). CLI commands use `txtTypeCliData` in the same format, and the app maps `forceFlood` to attempt `3` when sending.
- Group text packets (`PAYLOAD_TYPE_GRP_TXT`): payload is `[channel_hash (1)][MAC (2)][encrypted data...]`. Decrypted data layout is `[timestamp x4][txt_type][text...]` where text is `"sender: message"` (see MeshCore `BaseChatMesh::sendGroupMessage`). Sender identity is not in the payload; use `PUSH_CODE_LOG_RX_DATA` raw packet path bytes for origin hash when available.
- Routing hashes are public-key prefixes. Firmware negotiation currently supports 1–3 bytes per hop; packed path metadata must be decoded before counting or reversing hops. Use per-path hash width, not a fixed one-byte stride. See [routing paths](documentation/routing-paths.md).
- Regions: channel messages retain their send region; incoming regions are resolved from raw transport-flood codes against locally known names. Replies use a known original region by default, with an opt-out chip. See [regions](documentation/regions.md).
- Images: channel GRP_DATA framing is defined in `lib/services/image_chunk_transport.dart`. Native codec/model requirements are documented in [image messages](documentation/image-messages.md).
## Build, Test, and Development Commands
- Commands assume Flutter/Dart on PATH (or use your SDK's absolute path); see [CLAUDE.md](CLAUDE.md) for the full list.
- `flutter pub get` installs dependencies; `flutter run` launches the app; `flutter build apk --release` / `flutter build ios --release` produce release builds.
- CI checks: `dart format --output=none --set-exit-if-changed .`, `flutter analyze --fatal-infos --fatal-warnings`, and `flutter test`.
## Coding Style & Naming Conventions
- Follow `flutter_lints`, use `lowerCamelCase`/`UpperCamelCase`/`snake_case`, prefer `StatelessWidget` + `Consumer`, and use `const` constructors.
- Material widgets only (no Cupertino); center app bar titles (`centerTitle: true`); prefix private members with `_`.
- Keep screens simple, keep the main screens open and read-only when the radio disconnects (see `documentation/offline-mode.md`), and avoid premature abstractions (don't add a helper until it is needed in 3+ places).
- Avoid unnecessary comments, feature flags, and backwards-compatibility shims.
## Testing Guidelines
- Tests use `flutter_test`; add `*_test.dart` under `test/` and run `flutter test` before UI/protocol changes.
## Commit & Pull Request Guidelines
- Keep commit subjects short and action-focused; PRs should describe behavior changes, link issues, include screenshots for UI changes, and call out BLE protocol changes explicitly.
## Documentation maintenance
Keep user instructions in `documentation/` and use [ble-protocol.md](documentation/ble-protocol.md) as the canonical protocol reference. Update affected guides, feature limitations, and screenshots when changing user-facing behavior. Read [CONTRIBUTING.md](CONTRIBUTING.md) for branch and review requirements.