bvandeusen
d1e276204e
External media controllers (Android Wear, Auto, Bluetooth dashes, lock-screen widgets) consume the audio_service MediaSession and silently no-op on any action that isn't in the handler's systemActions set. Several handler methods were already implemented but never advertised, plus stop() defaulted to a no-op — which matched user reports of "media controller on the watch sometimes works but doesn't play nice with Minstrel." This patch lines the advertised surface up with what the handler actually implements + wires a native heart-rating button. **Expanded controls + systemActions:** - Added MediaControl.stop to the expanded controls list. - systemActions now also enumerates stop, skipToQueueItem (override shipped in v2026.05.13.1), setShuffleMode, setRepeatMode, and setRating. Without these in the set, Android 13+ drops the corresponding callbacks from external surfaces. **stop() override:** halts _player and dismisses the foreground notification via super.stop(). Default just flipped processingState to idle without releasing the audio session — external surfaces treated that as "paused forever". **setRating wiring (native heart-button protocol):** new LikeBridge adapter passes through configure() carrying toggleTrackLike + isTrackLiked closures over LikesController and likedIdsProvider. - setRating override flips the like through the bridge and re-emits mediaItem so the watch's heart icon updates immediately. - _toMediaItem populates MediaItem.rating on every track change so the right filled/outlined heart shows on track-A → track-B. - PlayerActions ref.listen on likedIdsProvider calls refreshCurrentRating so toggling a like from TrackRow / kebab / another device (SSE) also keeps the watch icon in sync. **artUri seed on first broadcast:** AlbumCoverCache.peekCached returns the file path synchronously when the cover is already on disk. _toMediaItem uses this so warm-cache tracks broadcast with artUri populated from the first frame — external controllers see the cover immediately instead of waiting for the later async _loadArtForCurrentItem path. Cold-cache tracks fall through to that path unchanged.
Minstrel mobile client
Flutter (iOS + Android) sibling of the SvelteKit web SPA. v1 first slice ships: scaffold, auth, library browse (home / artist / album), likes, player with background audio + lock-screen controls.
Setup
cd flutter_client
flutter pub get
./tool/sync_shared.sh # copy tokens / error-copy / placeholders from ../web
dart run tool/gen_tokens.dart # regen lib/theme/tokens.dart from shared/fabledsword.tokens.json
flutter run
sync_shared.sh is idempotent. CI runs it on every build; rerun locally
whenever web/src/lib/styles/tokens.json,
web/src/lib/styles/error-copy.json, or
web/static/placeholders/album-fallback.svg changes.
Project layout
See docs/superpowers/specs/2026-05-02-flutter-mobile-foundation-design.md
section 3. Briefly:
lib/api/— dio client, ApiError, error-copy loader, per-surface endpoints.lib/auth/— server URL screen, login screen, AuthController + secure storage.lib/library/— home, artist detail, album detail, providers, widgets.lib/likes/— LikeButton + optimistic toggle controller.lib/player/— audio handler, player provider, mini PlayerBar, NowPlaying.lib/theme/— FabledSword token Dart class (generated), ThemeExtension, ThemeData.lib/shared/— routing (go_router shell), version gate, connection error banner.
shared/fabledsword.tokens.json and assets/error-copy.json are
synced from web/. Don't edit them directly — edit web/src/lib/styles/
and re-run ./tool/sync_shared.sh.
Architecture
- State: Riverpod 2 (
AsyncValue,AsyncNotifier, family providers). - HTTP: dio 5 with a Bearer-auth interceptor; 401 clears the session and the router redirects to login.
- Audio: just_audio wrapped by audio_service for background playback + lock-screen / notification controls.
- Auth: Bearer tokens in flutter_secure_storage. Server already
supports both cookie (web SPA) and Bearer (
internal/auth/session.go). - Routing: go_router with a ShellRoute so the PlayerBar persists
across navigation. Cold launch flow: no server-url →
/server-url, url set / no token →/login, token present →/home.
CI
.forgejo/workflows/flutter.yml runs on push to dev/main, tag pushes,
PR to main, and manual dispatch — path-filtered to flutter_client/**
plus the shared web inputs. Steps: sync, analyze, test, build APK.
Debug APKs upload as artifacts; release APKs attach to the Forgejo
release on tag.
Versioning
pubspec.yaml version mirrors the server tag (e.g. server v0.1.0
→ Flutter 0.1.0+1). The server's /healthz returns
min_client_version; old clients show an Update Required modal and
refuse to operate. Bump internal/server/version.go MinClientVersion
when a server-side change requires a paired client update.
Distribution
- Android: APK on the Forgejo release page. No Play Store for v1.
- iOS: TestFlight on tag (manual upload v1, automate later).
Out-of-scope for slice 1
Search, discover, requests, settings beyond server URL, admin, listening history, playlists, offline cache (#357). Those land in subsequent slices with their own brainstorm/spec/plan cycles. Per the operator's M7 ordering decision (2026-05-02), slice 2+ pauses to ship the missing web features first (#352 playlists, #362 theme toggle, #363 queue UI, #364 listening history, etc.) before mirroring on Flutter.