Add a desktop update check against GitHub Releases

Desktop ships as raw zips with no update path, so somebody who downloaded
v3.0.0 has no way to learn that v3.2.0 exists. Mobile is unaffected — the
App Store and Play update it.

UpdateController queries /releases/latest two seconds after first frame and
at most once a day, and shows a banner above the page body when the tag
parses to a newer version than package_info reports. Downloads open in the
browser: nothing is downloaded, verified or installed by the app. Real
one-click updates need Developer ID signing and notarization plus a Windows
installer first — see docs/auto-update.md.

The whole feature is gated on --dart-define=OV_CHANNEL=github, which only
the desktop jobs in release.yml pass. The default is `store`, so a build
that forgets the flag stays quiet rather than pointing App Store or Play
users at a GitHub zip.

Settings gains a manual "Check for updates" in About, next to the version it
is about, plus an Updates card for the auto-check preference and un-skipping
a passed-over release.

Author: awhitchurch

.github/workflows/release.yml

@@ -88,7 +88,10 @@ jobs:
           flutter pub get
 
       - name: Build Linux release
-        run: flutter build linux --release
+        # OV_CHANNEL=github enables the in-app update check (UpdateChannel).
+        # Only builds published here may point users at a GitHub Release zip;
+        # store builds must stay on the default `store` channel.
+        run: flutter build linux --release --dart-define=OV_CHANNEL=github
 
       - name: Package
         run: |
@@ -143,7 +146,10 @@ jobs:
           flutter pub get
 
       - name: Build Linux release
-        run: flutter build linux --release
+        # OV_CHANNEL=github enables the in-app update check (UpdateChannel).
+        # Only builds published here may point users at a GitHub Release zip;
+        # store builds must stay on the default `store` channel.
+        run: flutter build linux --release --dart-define=OV_CHANNEL=github
 
       - name: Package
         run: |
@@ -187,7 +193,7 @@ jobs:
           # can silence it here instead of patching the plugin. Remove once
           # permission_handler_windows moves to <coroutine>.
           CL: /D_SILENCE_EXPERIMENTAL_COROUTINE_DEPRECATION_WARNINGS
-        run: flutter build windows --release
+        run: flutter build windows --release --dart-define=OV_CHANNEL=github
 
       - name: Package
         shell: pwsh
@@ -245,7 +251,10 @@ jobs:
       - name: Build macOS release
         run: |
           # Generate the ephemeral xcconfig / plugin registrant without building.
-          flutter build macos --release --config-only
+          # The --dart-define is baked into Flutter-Generated.xcconfig here, so
+          # the xcodebuild step below inherits it.
+          flutter build macos --release --config-only \
+            --dart-define=OV_CHANNEL=github
 
           # ARCHS + ONLY_ACTIVE_ARCH=NO force a universal (Intel + Apple Silicon)
           # binary; the pods (libserialport) build both slices from source.

docs/auto-update.md

@@ -0,0 +1,116 @@
+# Auto-update — phase 1 (check and notify)
+
+Written 2026-09-10. Implements the desktop update check; **phase 2 (true
+one-click update) is not built** — see the bottom of this file for what it
+needs.
+
+## The shape of the problem
+
+| Platform | How it updates | What OpenView does |
+| --- | --- | --- |
+| iOS / Android | App Store, Google Play | Nothing. The store updates it. |
+| Desktop (GitHub Release zips) | Nothing — the user must notice a new release | Checks daily, shows a banner, opens the download in a browser |
+
+Desktop is the whole problem: `.github/workflows/release.yml` publishes raw
+zips, so somebody who downloaded v3.0.0 has no way to learn that v3.2.0 exists.
+
+## What phase 1 does
+
+1. Two seconds after first frame, [`UpdateController.checkAtStartup`](../lib/controllers/update_controller.dart)
+   GETs `/repos/Protocentral/protocentral_openview/releases/latest`.
+2. If the tag parses to a version newer than `package_info_plus` reports, the
+   [`UpdateBanner`](../lib/ui/widgets/update_banner.dart) appears above the page
+   body with **What's new** / **Download** / dismiss.
+3. **Download** opens the matching release asset in the user's browser. Nothing
+   is downloaded, verified, or installed by the app.
+
+The same check runs on demand from Settings → About → **Check for updates**.
+
+It never blocks startup, never throws out of the check, and stays silent when
+offline or rate-limited.
+
+## The distribution-channel gate
+
+`UpdateChannel.isSelfDistributed` is the master switch, and it is
+`String.fromEnvironment('OV_CHANNEL')` — **`store` by default**, so a build that
+forgets the flag stays quiet rather than nagging App Store or Play users with a
+GitHub zip. Only the desktop jobs in `release.yml` pass
+`--dart-define=OV_CHANNEL=github`.
+
+When it is off, the whole feature is absent: no check, no banner, and no
+Updates card in Settings. Future distro packages (Flathub, AUR) should stay on
+the default so the package manager keeps ownership of updating.
+
+To exercise the flow locally:
+
+```sh
+flutter run -d macos --dart-define=OV_CHANNEL=github
+```
+
+Because the tag will match your own version, Settings → About will say "You are
+running the latest release" rather than showing a banner. To see the banner,
+temporarily lower `version:` in `pubspec.yaml`.
+
+## Things that are easy to break
+
+- **Asset names are duplicated.** `UpdateController.assetNameForCurrentPlatform`
+  hard-codes the four zip names produced by the `Package` steps in
+  `release.yml`. Rename one there without renaming it here and the dialog
+  quietly degrades to the release page instead of a direct download.
+  `test/update_controller_test.dart` pins the names but cannot see the workflow.
+- **Rate limit.** Unauthenticated GitHub API is 60 requests/hour *per IP*. One
+  check per day per user is nowhere near it, but a shared lab NAT plus a tight
+  loop would be — hence `lastUpdateCheck` in `openview_settings.json` and the
+  24 h `_checkInterval`.
+- **`/releases/latest` excludes prereleases**, which is what we want: a
+  `v3.3.0-rc1` tag must not nag stable users. Do not switch to `/releases`
+  without re-adding that filter.
+- **Release notes are Markdown**, and OpenView has no Markdown renderer.
+  `_ReleaseNotes` flattens headings, bullets and emphasis by hand and collapses
+  PR URLs to `#123`. It is deliberately dumb — if the notes ever need real
+  rendering, add `flutter_markdown` rather than growing that function.
+
+## User controls
+
+**Settings → About → Check for updates** is the manual check, sitting next to
+the version it is about — the familiar desktop "About → Check for Updates…"
+idiom. It ignores both the daily cadence and any skipped version (the user
+asked), and reports the same way: the release-notes dialog when there is
+something, a snackbar when there isn't. The line beside the button carries the
+standing state — last checked, up to date, or the error from the last attempt.
+
+**Settings → Updates** carries the preferences only, so there is exactly one
+check button on the screen:
+
+- **Check for updates automatically** — persisted as `autoCheckUpdates`.
+- **What's new in x.y.z** — reopens the dialog after a check has found
+  something.
+- **Un-skip x.y.z** — clears `skippedUpdateVersion`.
+
+Both are absent on store builds. Dismissing the banner with the × hides it for
+the session; **Skip this version** in the dialog suppresses it for good.
+
+## Phase 2 — what real one-click updates need
+
+The standard answer for desktop Flutter is
+[`auto_updater`](https://pub.dev/packages/auto_updater), which wraps **Sparkle**
+(macOS) and **WinSparkle** (Windows) and consumes an `appcast.xml` published
+alongside the release. Its prerequisites are not met today:
+
+1. **macOS must be Developer ID signed and notarized.** The macOS job currently
+   ad-hoc signs (`CODE_SIGN_IDENTITY=-`), which is also why Gatekeeper warns on
+   first launch. Sparkle cannot install an update over an ad-hoc-signed app.
+   The `AC_CERTIFICATE` / `APPLE_*` secrets for this already exist in the repo.
+2. **Windows needs an installer** (MSIX or Inno Setup), not a zip — WinSparkle
+   updates by running one. Without an OV/EV code-signing cert, SmartScreen will
+   flag every build.
+3. **Linux is not supported by `auto_updater` at all.** Linux stays on the
+   phase-1 notify path, or moves to Flathub and lets the package manager own it.
+
+Do the signing and notarization first — it fixes the Gatekeeper warning on its
+own merits, and everything else is blocked behind it.
+
+Deliberately **not** on the roadmap: downloading and swapping the app bundle
+ourselves. macOS quarantine and Gatekeeper, Windows file locks on the running
+`.exe`, and hand-rolled signature verification are exactly what Sparkle and
+WinSparkle exist to handle.

lib/app.dart

@@ -12,6 +12,7 @@ import 'controllers/smp_controller.dart';
 import 'controllers/recordings_browser_controller.dart';
 import 'controllers/scan_controller.dart';
 import 'controllers/settings_controller.dart';
+import 'controllers/update_controller.dart';
 import 'theme/app_theme.dart';
 import 'transport/ble_service.dart';
 import 'transport/usb_serial_service.dart';
@@ -30,6 +31,7 @@ class OpenViewApp extends StatelessWidget {
   final RecordingsBrowserController recordingsBrowser;
   final DeveloperBleController developerBle;
   final SmpController smp;
+  final UpdateController update;
 
   const OpenViewApp({
     super.key,
@@ -44,6 +46,7 @@ class OpenViewApp extends StatelessWidget {
     required this.recordingsBrowser,
     required this.developerBle,
     required this.smp,
+    required this.update,
   });
 
   @override
@@ -63,6 +66,7 @@ class OpenViewApp extends StatelessWidget {
         ChangeNotifierProvider<DeveloperBleController>.value(
             value: developerBle),
         ChangeNotifierProvider<SmpController>.value(value: smp),
+        ChangeNotifierProvider<UpdateController>.value(value: update),
       ],
       child: Consumer<SettingsController>(
         builder: (_, settings, __) => MaterialApp.router(

lib/controllers/settings_controller.dart

@@ -25,6 +25,9 @@ class SettingsController extends ChangeNotifier {
   ThemeMode _themeMode = ThemeMode.dark;
   int _repaintHz = PlatformV3.isDesktop ? 60 : 30;
   String? _recordingDir; // null → default under Documents/
+  bool _autoCheckUpdates = true;
+  DateTime? _lastUpdateCheck;
+  String? _skippedUpdateVersion;
 
   ThemeMode get themeMode => _themeMode;
   int get repaintHz => _repaintHz;
@@ -33,6 +36,18 @@ class SettingsController extends ChangeNotifier {
   String? get recordingDirOverride => _recordingDir;
   bool get isDefaultRecordingDir => _recordingDir == null;
 
+  /// Whether OpenView may check GitHub Releases for a newer desktop build on
+  /// startup. Only self-distributed builds ever check (see UpdateChannel),
+  /// but the preference is stored for every platform so toggling it on a
+  /// store build is harmless.
+  bool get autoCheckUpdates => _autoCheckUpdates;
+
+  /// When the last update check completed, used to keep it to once a day.
+  DateTime? get lastUpdateCheck => _lastUpdateCheck;
+
+  /// A release the user asked not to be reminded about, e.g. `3.3.0`.
+  String? get skippedUpdateVersion => _skippedUpdateVersion;
+
   File? _file;
 
   Future<void> load() async {
@@ -49,6 +64,13 @@ class SettingsController extends ChangeNotifier {
       if (dirOverride != null && dirOverride.trim().isNotEmpty) {
         _recordingDir = dirOverride;
       }
+      _autoCheckUpdates = json['autoCheckUpdates'] as bool? ?? _autoCheckUpdates;
+      final lastCheck = json['lastUpdateCheck'] as String?;
+      if (lastCheck != null) _lastUpdateCheck = DateTime.tryParse(lastCheck);
+      final skipped = json['skippedUpdateVersion'] as String?;
+      if (skipped != null && skipped.trim().isNotEmpty) {
+        _skippedUpdateVersion = skipped;
+      }
     } catch (_) {
       // Corrupt / unreadable settings — fall back to defaults silently.
     }
@@ -85,6 +107,29 @@ class SettingsController extends ChangeNotifier {
     await _save();
   }
 
+  Future<void> setAutoCheckUpdates(bool enabled) async {
+    if (enabled == _autoCheckUpdates) return;
+    _autoCheckUpdates = enabled;
+    notifyListeners();
+    await _save();
+  }
+
+  /// Stamp the update check clock. Called after every completed check —
+  /// including one that found nothing — so a quiet repo doesn't cause a
+  /// request on every launch.
+  Future<void> markUpdateChecked() async {
+    _lastUpdateCheck = DateTime.now();
+    await _save();
+  }
+
+  /// Suppress reminders for [version] (pass null to clear).
+  Future<void> setSkippedUpdateVersion(String? version) async {
+    if (version == _skippedUpdateVersion) return;
+    _skippedUpdateVersion = version;
+    notifyListeners();
+    await _save();
+  }
+
   /// Resolve the effective recordings directory (default or override).
   Future<Directory> recordingsDirectory() async {
     final override = _recordingDir;
@@ -103,6 +148,9 @@ class SettingsController extends ChangeNotifier {
         'themeMode': _themeMode.name,
         'repaintHz': _repaintHz,
         'recordingDir': _recordingDir,
+        'autoCheckUpdates': _autoCheckUpdates,
+        'lastUpdateCheck': _lastUpdateCheck?.toIso8601String(),
+        'skippedUpdateVersion': _skippedUpdateVersion,
       }));
     } catch (_) {
       // Best-effort persistence; ignore write failures.