docs: stop pointing at the deleted Flutter tree — #2710

Every comment naming a path in flutter_client/ now resolves to nothing, which is the failure mode this project has already been bitten by twice -- drift #572 came from delete.go describing behaviour it no longer had, and that same docstring was still wrong when it was fixed last week. A pointer to a deleted directory is the same thing in slower motion: the reader follows it, finds nothing, and cannot tell whether the comment is stale or they are looking in the wrong place. Three treatments, per what each comment was actually doing: - Naming a concept ("mirrors db.dart's CachedTracks Drift table"): keep the concept, drop the path. The Drift table is why the entity looks as it does; the file it lived in is not. - Pure port bookkeeping ("Mirrors <path>." and nothing else): deleted. Git history records the port; the comment only restated it. - Substance introduced by a pointer (a lifecycle list, a 200 px/s threshold, an inverted control-row placement): keep the substance, drop the lead-in. The two Go comments were the valuable ones and got more than a trim. They stated a live contract -- "field names match the client's FromJson helpers exactly, or fields are silently dropped" -- against a client that no longer exists. They now name the real consumer, SyncResponseWire.kt, and say why the failure is silent there too: kotlinx.serialization skips unknown keys, so a renamed field arrives as a default value rather than an error. The ticket counted 64 files by grepping flutter_client/. A second tier turned up during the sweep: 15 more references naming bare Dart files (player_bar.dart, now_playing_screen.dart:464, auth_provider.dart) with no directory prefix. Same dead tree, same treatment, folded in here. Comments only -- verified no non-comment line is touched in the diff.
2026-08-16 22:40:58 -04:00
parent 0036f534db
commit 03a8d12079
77 changed files with 89 additions and 131 deletions
@@ -11,8 +11,6 @@ import javax.inject.Singleton

 /**
 * Read-through accessor for the admin cross-user requests queue.
- * Mirrors `flutter_client/lib/admin/admin_providers.dart`'s
- * AdminRequestsController.
 *
 * No Room caching — admin actions are infrequent and don't benefit
 * from offline scrollback. `approve` and `reject` fire direct REST
@@ -8,8 +8,7 @@ import java.io.IOException

 /**
 * Maps server error codes (and common transport failures) to
- * friendly, sentence-case copy. Mirrors
- * `flutter_client/assets/error-copy.json` + `error_copy.dart`.
+ * friendly, sentence-case copy.
 *
 * Server errors are `{"error":{"code":"...","message":"..."}}`.
 * [fromThrowable] pulls the code out of a Retrofit [HttpException]'s
@@ -10,8 +10,7 @@ import retrofit2.http.POST
 import retrofit2.http.Path

 /**
- * Retrofit interface for `/api/admin/invites`. Mirrors
- * `flutter_client/lib/api/endpoints/admin_invites.dart`.
+ * Retrofit interface for `/api/admin/invites`.
 *
 * Server TTL is hardcoded at 24h; the only configurable field is the
 * optional `note` on create.
@@ -6,8 +6,7 @@ import retrofit2.http.POST
 import retrofit2.http.Path

 /**
- * Retrofit interface for `/api/admin/quarantine`. Mirrors
- * `flutter_client/lib/api/endpoints/admin_quarantine.dart`.
+ * Retrofit interface for `/api/admin/quarantine`.
 *
 * Three resolution endpoints:
 *   - `resolve`        → admin reviewed, no action taken (clears flags).
@@ -6,8 +6,7 @@ import retrofit2.http.POST
 import retrofit2.http.Path

 /**
- * Retrofit interface for `/api/admin/requests`. Mirrors
- * `flutter_client/lib/api/endpoints/admin_requests.dart`.
+ * Retrofit interface for `/api/admin/requests`.
 *
 * Server returns the same `requestView` shape as the user-side
 * `/api/requests`, so RequestWire is reused. Different listing scope —
@@ -10,8 +10,7 @@ import retrofit2.http.PUT
 import retrofit2.http.Path

 /**
- * Retrofit interface for `/api/admin/users`. Mirrors
- * `flutter_client/lib/api/endpoints/admin_users.dart`.
+ * Retrofit interface for `/api/admin/users`.
 *
 * Note: the PUT-auto-approve body field is `auto_approve`, NOT
 * `auto_approve_requests` — the request shape differs from the
@@ -6,8 +6,7 @@ import retrofit2.http.Body
 import retrofit2.http.POST

 /**
- * Retrofit interface for `/api/auth`. Mirrors
- * `flutter_client/lib/api/endpoints/auth.dart`.
+ * Retrofit interface for `/api/auth`.
 *
 * The actual session-cookie capture happens in
 * [com.fabledsword.minstrel.api.AuthCookieInterceptor]; we don't
@@ -14,7 +14,6 @@ import retrofit2.http.Query

 /**
 * Retrofit interface for Discover / Lidarr search / request creation.
- * Mirrors `flutter_client/lib/api/endpoints/discover.dart`.
 *
 * `/api/lidarr/search` has a 60s LRU on the server so quick re-types
 * of the same query are cheap.
@@ -9,8 +9,7 @@ import retrofit2.http.Body
 import retrofit2.http.POST

 /**
- * Retrofit interface for `POST /api/events`. Mirrors the relevant
- * slice of `flutter_client/lib/api/endpoints/events.dart`. All four
+ * Retrofit interface for `POST /api/events`. All four
 * variants share the same URL — the discriminator is in the request
 * body's `type` field. Server contract is best-effort per spec;
 * callers (the live path in PlayEventsReporter) swallow errors and
@@ -5,10 +5,9 @@ import retrofit2.http.GET
 import retrofit2.http.Query

 /**
- * Retrofit interface for `/api/me/history`. Mirrors the relevant
- * subset of `flutter_client/lib/api/endpoints/me.dart` (only
- * `history()`; profile / timezone / quarantine endpoints land with
- * their respective phases).
+ * Retrofit interface for `/api/me/history` — history only. The profile,
+ * timezone and quarantine endpoints on `/api/me` live with their own
+ * features rather than here.
 */
 interface HistoryApi {
    @GET("api/me/history")
@@ -4,10 +4,9 @@ import com.fabledsword.minstrel.models.wire.HomeIndexWire
 import retrofit2.http.GET

 /**
- * Retrofit interface for the Home discovery endpoint. Mirrors
- * `flutter_client/lib/api/endpoints/home.dart` — just the ID-only
- * `/api/home/index` variant. The Flutter port has a heavier
- * `/api/home` (full embedded payload) too; we don't use it because
+ * Retrofit interface for the Home discovery endpoint. Only the ID-only
+ * `/api/home/index` variant is used. The server also serves a heavier
+ * `/api/home` (full embedded payload); we don't use it because
 * the per-item hydration path (sync controller → Room → Flow) is
 * the only one the native client needs.
 */
@@ -13,7 +13,6 @@ import retrofit2.http.Query

 /**
 * Retrofit interface for the server's native `/api/...` library surface.
- * Mirrors `flutter_client/lib/api/endpoints/library.dart` 1:1.
 *
 * Notes on shapes:
 *   - `GET /api/artists/{id}` returns ArtistDetailWire (ArtistRef fields
@@ -7,8 +7,7 @@ import retrofit2.http.POST
 import retrofit2.http.Path

 /**
- * Retrofit interface for `/api/likes`. Mirrors
- * `flutter_client/lib/api/endpoints/likes.dart`.
+ * Retrofit interface for `/api/likes`.
 *
 * Path segment `kind` is one of "artists" | "albums" | "tracks"
 * (plural, matching the server route). The Repository hides that
@@ -11,7 +11,6 @@ import retrofit2.http.PUT

 /**
 * Retrofit interface for the `/api/me` endpoints — caller-scoped account endpoints.
- * Mirrors the relevant slice of `flutter_client/lib/api/endpoints/settings.dart`.
 *
 * History + timezone + system-playlists-status live under /api/me too
 * but are handled by their respective feature repositories; this
@@ -11,8 +11,7 @@ import retrofit2.http.Path
 import retrofit2.http.Query

 /**
- * Retrofit interface for `/api/playlists`. Mirrors
- * `flutter_client/lib/api/endpoints/playlists.dart`.
+ * Retrofit interface for `/api/playlists`.
 */
 interface PlaylistsApi {
    /**
@@ -54,7 +53,7 @@ interface PlaylistsApi {
     * the system playlist's tracks in rotation-aware order without
     * rebuilding — used by the Home play-button overlay so taps on For
     * You / Discover / Today's mix advance rotation rather than picking
-     * the stored order. Mirrors `playlists.dart.systemShuffle`.
+     * the stored order.
     */
    @GET("api/playlists/system/{kind}/shuffle")
    suspend fun systemShuffle(@Path("kind") variant: String): PlaylistDetailWire
@@ -8,9 +8,8 @@ import retrofit2.http.POST
 import retrofit2.http.Path

 /**
- * Retrofit interface for `/api/quarantine`. Mirrors the relevant
- * parts of `flutter_client/lib/api/endpoints/quarantine.dart` (flag
- * and unflag) plus the `/api/quarantine/mine` endpoint from `me.dart`.
+ * Retrofit interface for `/api/quarantine`: flag and unflag, plus the
+ * `/api/quarantine/mine` listing.
 *
 * Both flag and unflag are user-scoped — callers act on their own
 * quarantine entries. The cross-user admin surface is a separate
@@ -5,9 +5,7 @@ import retrofit2.http.GET
 import retrofit2.http.Query

 /**
- * Retrofit interface for `/api/radio`. Mirrors the relevant slice of
- * `flutter_client/lib/api/endpoints/radio.dart` (a single GET that
- * returns the seeded queue). The server picks a fresh shuffle each
+ * Retrofit interface for `/api/radio`. The server picks a fresh shuffle each
 * invocation — clients call this once per radio start.
 */
 interface RadioApi {
@@ -6,8 +6,7 @@ import retrofit2.http.GET
 import retrofit2.http.Path

 /**
- * Retrofit interface for the user-side `/api/requests`. Mirrors
- * `flutter_client/lib/api/endpoints/requests.dart`.
+ * Retrofit interface for the user-side `/api/requests`.
 *
 * Server scopes results to the caller — admins see only their own
 * requests through this endpoint. The cross-user admin view lives on
@@ -5,8 +5,7 @@ import retrofit2.http.GET
 import retrofit2.http.Query

 /**
- * Retrofit interface for `GET /api/search`. Mirrors
- * `flutter_client/lib/api/endpoints/search.dart`. Server returns 400
+ * Retrofit interface for `GET /api/search`. Server returns 400
 * on empty/whitespace-only `q` — the caller is responsible for
 * guarding.
 */
@@ -17,8 +17,7 @@ import javax.inject.Inject
 import javax.inject.Singleton

 /**
- * Singleton facade over the auth state machine. Mirrors Flutter's
- * `AuthController` from `auth_provider.dart`.
+ * Singleton facade over the auth state machine.
 *
 * Cookie persistence is handled by [AuthCookieInterceptor] capturing
 * Set-Cookie on the login response; the user identity itself
@@ -12,8 +12,7 @@ import javax.inject.Singleton
 private const val POOL_LIMIT = 100

 /**
- * Offline play sources over the local audio-cache index. Mirrors
- * `flutter_client/lib/cache/shuffle_source.dart`.
+ * Offline play sources over the local audio-cache index.
 *
 * Both pools are UNIONs over the cache regardless of storage bucket
 * (liked AND recently-played both included). The two-bucket split is
@@ -1,7 +1,7 @@
 package com.fabledsword.minstrel.cache.audiocache

 /**
- * Defaults for the 2-bucket audio cache. Matches the Flutter client.
+ * Defaults for the 2-bucket audio cache.
 *
 *  - `likedCapBytes`: cap for the protected bucket — cached files for
 *    tracks the user has liked. Evicted only after the rolling bucket
@@ -6,8 +6,7 @@ private const val FIVE_GIB_BYTES = 5L * 1024 * 1024 * 1024
 private const val DEFAULT_PREFETCH_WINDOW = 5

 /**
- * User-tunable audio cache settings. Mirrors Flutter's `CacheSettings`
- * (cache_settings_provider.dart) field-for-field. Persisted as a JSON
+ * User-tunable audio cache settings. Persisted as a JSON
 * blob on the auth_session single-row table via [AuthStore].
 *
 * - [likedCapBytes]: budget for cached files of liked tracks. 0 means
@@ -59,7 +59,6 @@ interface CachedPlaylistDao {

    /**
     * Atomically reconciles the cache against the fresh list response.
-     * Mirrors `flutter_client/lib/playlists/playlists_provider.dart:54` —
     * `BuildSystemPlaylists` rotates system-playlist UUIDs every
     * rebuild, so upsert alone leaves stale rows whose detail fetch
     * 404s. Delete any of the user's rows not in [freshOwnedIds] (this
@@ -8,7 +8,7 @@ import kotlinx.datetime.Instant

 /**
 * One row per fully-downloaded audio file. Mirrors
- * `flutter_client/lib/cache/db.dart`'s `AudioCacheIndex` Drift table.
+ * the Flutter client's `AudioCacheIndex` Drift table.
 *
 * Drives the 2-bucket LRU eviction (Phase 12 AudioCacheEvictionWorker):
 *   - `incidental` files (streamed-and-cached side effect) evict first
@@ -6,7 +6,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant

 /**
- * Cache row for one album. Mirrors `flutter_client/lib/cache/db.dart`'s
+ * Cache row for one album. Mirrors the Flutter client's
 * `CachedAlbums` Drift table.
 */
@Entity(tableName = "cached_albums")
@@ -6,7 +6,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant

 /**
- * Cache row for one artist. Mirrors `flutter_client/lib/cache/db.dart`'s
+ * Cache row for one artist. Mirrors the Flutter client's
 * `CachedArtists` Drift table.
 *
 * Column names follow Kotlin idiom (camelCase) rather than Drift's
@@ -6,7 +6,7 @@ import kotlinx.datetime.Instant

 /**
 * Per-item row driving the Home screen sections. Mirrors
- * `flutter_client/lib/cache/db.dart`'s `CachedHomeIndex` Drift table.
+ * the Flutter client's `CachedHomeIndex` Drift table.
 *
 * `section` is one of (matching /api/home keys):
 *   - "recently_added_albums"
@@ -5,7 +5,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant

 /**
- * Like membership row. Mirrors `flutter_client/lib/cache/db.dart`'s
+ * Like membership row. Mirrors the Flutter client's
 * `CachedLikes` Drift table. Composite primary key — one user may
 * independently like a track AND its album AND its artist; rows are
 * disambiguated by the (userId, entityType, entityId) triple.
@@ -7,7 +7,7 @@ import kotlinx.datetime.Instant

 /**
 * One row per pending offline-write. Mirrors
- * `flutter_client/lib/cache/db.dart`'s `CachedMutations` Drift table.
+ * the Flutter client's `CachedMutations` Drift table.
 *
 * MutationQueue.enqueue() inserts a row when a server-write fails with
 * an IOException; MutationReplayer.drain() pops and re-attempts each
@@ -7,7 +7,7 @@ import kotlinx.datetime.Instant

 /**
 * Cache row for one playlist (user or system). Mirrors
- * `flutter_client/lib/cache/db.dart`'s `CachedPlaylists` Drift table.
+ * the Flutter client's `CachedPlaylists` Drift table.
 *
 * `systemVariant` is null for user playlists and one of
 * "for_you" / "songs_like_artist" / "discover" / "todays_mix" / etc.
@@ -4,7 +4,7 @@ import androidx.room.Entity

 /**
 * Ordered membership of tracks within a playlist. Mirrors
- * `flutter_client/lib/cache/db.dart`'s `CachedPlaylistTracks` Drift table.
+ * the Flutter client's `CachedPlaylistTracks` Drift table.
 * Composite PK so the same track can only appear once per playlist;
 * `position` carries the ordering.
 */
@@ -7,7 +7,7 @@ import kotlinx.datetime.Instant

 /**
 * The current user's quarantine flag for one track. Mirrors
- * `flutter_client/lib/cache/db.dart`'s `CachedQuarantineMine` Drift
+ * the Flutter client's `CachedQuarantineMine` Drift
 * table.
 *
 * The flat denormalized track/album/artist columns let the Quarantine
@@ -8,7 +8,7 @@ import kotlinx.datetime.Instant
 /**
 * Single-row snapshot of the last playback session — queue (as JSON),
 * current index, position, and source tag. Mirrors
- * `flutter_client/lib/cache/db.dart`'s `CachedResumeState` Drift table.
+ * the Flutter client's `CachedResumeState` Drift table.
 *
 * Lets a torn-down session (the player's idle/dismissed teardown)
 * resume on next launch; without it the headset / lock-screen play
@@ -6,7 +6,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant

 /**
- * Cache row for one track. Mirrors `flutter_client/lib/cache/db.dart`'s
+ * Cache row for one track. Mirrors the Flutter client's
 * `CachedTracks` Drift table.
 */
@Entity(tableName = "cached_tracks")
@@ -38,8 +38,7 @@ private const val BACKOFF_FACTOR = 2
 * ViewModels + the central [LiveEventsDispatcher]) collect filtered
 * subsets of the stream.
 *
- * Connection lifecycle mirrors
- * `flutter_client/lib/shared/live_events_provider.dart`:
+ * Connection lifecycle:
 * - Gated on having a session cookie. Subscription opens when the
 *   cookie transitions to non-null and closes when it transitions
 *   back to null (sign-out).
@@ -5,7 +5,7 @@ import kotlinx.serialization.json.JsonObject

 /**
 * Parsed event from the server's SSE stream. Mirrors
- * `flutter_client/lib/shared/live_events_provider.dart`'s `LiveEvent`.
+ * the Flutter client's `LiveEvent`.
 *
 * - [kind] is the SSE `event:` field (e.g. "track.liked", "playlist.deleted").
 * - [userId] is the actor whose user-scoped state changed (empty for
@@ -11,8 +11,7 @@ import javax.inject.Inject
 import javax.inject.Singleton

 /**
- * Maps incoming [LiveEvent]s to cross-screen state refreshes. Mirrors
- * `flutter_client/lib/shared/live_events_dispatcher.dart`. Activated
+ * Maps incoming [LiveEvent]s to cross-screen state refreshes. Activated
 * by force-@Inject in MinstrelApplication.
 *
 * Scope is deliberately narrow: this dispatcher only touches state
@@ -204,8 +204,7 @@ private const val HOURS_PER_DAY = 24L
 private const val DAYS_PER_WEEK = 7L

 /**
- * Lightweight relative-time formatter mirroring Flutter's
- * `library_screen.dart`'s `_relativeTime`:
+ * Lightweight relative-time formatter:
 *
 *   < 1h   → "Nm ago"
 *   < 24h  → "Nh ago"
@@ -1172,7 +1172,7 @@ enum class OfflinePoolKind(val label: String) {
 * first / greyed after, and the "building/pending" placeholders are dropped
 * (they need the server to generate, so they're meaningless offline).
 *
- * Diverges from Flutter (`flutter_client/lib/library/home_screen.dart`
+ * Diverges from Flutter (the Flutter client
 * `_buildPlaylistsRow`) which only shows the 5 fixed slots and never
 * surfaces the secondary kinds on Home. Operator authorized the
 * divergence on 2026-06-01; web UI catch-up tracked as task #53.
@@ -1374,7 +1374,7 @@ private const val MOST_PLAYED_COVER_DP = 48

 // 3 rows of MOST_PLAYED_TILE_HEIGHT_DP + 2 * 8dp inter-row spacing,
 // rounded up. Mirrors Flutter (`CompactTrackCard` in
-// flutter_client/lib/library/widgets/compact_track_card.dart) which
+// the Flutter client) which
 // uses a horizontal-row card pattern - much denser than the square
 // per-track tiles that web uses (operator request 2026-06-01: "in the
 // flutter iteration the tiles were different and smaller so more of
@@ -55,7 +55,7 @@ import com.fabledsword.minstrel.shared.widgets.SkeletonArtistTile
 * Library tab. Seven-tab TabBar (Artists / Albums / Genres / Years /
 * History / Liked / Hidden), matching the web client's library tab bar.
 * Genres and Years arrived with #2467; the rest predate it and mirrored
- * `flutter_client/lib/library/library_screen.dart`.
+ * the Flutter client.
 *
 * Artists + Albums are wired against the existing LibraryViewModel
 * (cache-first reads of cached_artists / cached_albums). The other
@@ -2,7 +2,7 @@ package com.fabledsword.minstrel.models

 /**
 * Lightweight reference to one album. Mirrors
- * `flutter_client/lib/models/album.dart`'s `AlbumRef`.
+ * the Flutter client's `AlbumRef`.
 *
 * `coverUrl` and `durationSec` match the server contract (not
 * `cover_art_url` / `duration_ms`). `year` is omitempty server-side so
@@ -2,7 +2,7 @@ package com.fabledsword.minstrel.models

 /**
 * Lightweight reference to one artist. Mirrors
- * `flutter_client/lib/models/artist.dart`'s `ArtistRef`.
+ * the Flutter client's `ArtistRef`.
 *
 * `coverUrl` is the server's field name (NOT cover_art_url). Server emits
 * empty string when the artist has no representative album cover; UI code
@@ -14,7 +14,7 @@ enum class LidarrRequestKind {
 }

 /**
- * Lidarr search hit. Mirrors `flutter_client/lib/models/lidarr.dart`'s
+ * Lidarr search hit. Mirrors the Flutter client's
 * `LidarrSearchResult` — `mbid` is the result's own MBID; `artistMbid`
 * and `albumMbid` are filled when the row is an album/track and the
 * UI needs the parent IDs to build the request.
@@ -2,7 +2,7 @@ package com.fabledsword.minstrel.models

 /**
 * Domain shape for one admin-issued registration invite. Mirrors
- * `flutter_client/lib/models/invite.dart Invite` and the server's
+ * the Flutter client's `Invite` and the server's
 * `inviteResp` from `internal/api/admin_invites.go`.
 *
 * `invitedBy` and `redeemedBy` are UUIDs of users (not usernames);
@@ -2,7 +2,7 @@ package com.fabledsword.minstrel.models

 /**
 * Caller's ListenBrainz integration state. Mirrors
- * `flutter_client/lib/models/my_profile.dart ListenBrainzStatus`
+ * the Flutter client's `ListenBrainzStatus`
 * and the server's `listenBrainzResp`.
 *
 * The token itself is never read back from the server — `tokenSet`
@@ -2,7 +2,7 @@ package com.fabledsword.minstrel.models

 /**
 * Lightweight reference to one playlist (user or system-generated).
- * Mirrors `flutter_client/lib/models/playlist.dart`'s `Playlist`.
+ * Mirrors the Flutter client's `Playlist`.
 *
 * `systemVariant` discriminates user vs. system playlists — null for
 * user-owned, one of "for_you" / "discover" / "songs_like_artist" / etc.
@@ -24,7 +24,7 @@ enum class RequestStatus {

 /**
 * One Lidarr request the user has submitted. Mirrors
- * `flutter_client/lib/models/admin_request.dart AdminRequest` —
+ * the Flutter client's `AdminRequest` —
 * shared between the user-side `/api/requests` view and the admin
 * cross-user view since the wire shape is identical.
 *
@@ -3,8 +3,7 @@ package com.fabledsword.minstrel.models
 /**
 * Caller's most recent system_playlist_runs state, driving the Home
 * placeholder cards for not-yet-generated system playlists. Mirrors
- * `flutter_client/lib/models/system_playlists_status.dart` and the
- * server's `systemPlaylistsStatusResp`.
+ * the server's `systemPlaylistsStatusResp`.
 *
 * Zero values (inFlight=false, both timestamps null) mean the user
 * has never had a build attempted — the placeholders read as
@@ -4,7 +4,7 @@ import kotlinx.serialization.Serializable

 /**
 * Lightweight reference to one track. Mirrors
- * `flutter_client/lib/models/track.dart`'s `TrackRef`.
+ * the Flutter client's `TrackRef`.
 *
 * The `Ref` suffix matches the Flutter convention — these types carry
 * only the IDs + display fields needed for list rendering + the player
@@ -2,7 +2,7 @@ package com.fabledsword.minstrel.models

 /**
 * Wire shape returned by `GET /api/client/version`. Mirrors
- * `flutter_client/lib/update/update_info.dart UpdateInfo`.
+ * the Flutter client's `UpdateInfo`.
 *
 * `version` is the server-bundled APK version (may have a leading
 * "v" from the git tag); `apkUrl` is server-relative (e.g.
@@ -4,7 +4,7 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable

 /**
- * Wire shape for `AlbumRef`. Mirrors `flutter_client/lib/models/album.dart`.
+ * Wire shape for `AlbumRef`.
 */
@Serializable
 data class AlbumWire(
@@ -4,7 +4,7 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable

 /**
- * Wire shape for `ArtistRef`. Mirrors `flutter_client/lib/models/artist.dart`.
+ * Wire shape for `ArtistRef`.
 */
@Serializable
 data class ArtistWire(
@@ -6,7 +6,7 @@ import kotlinx.serialization.Serializable
 /**
 * One row of `GET /api/lidarr/search`. Mirrors
 * `web/src/lib/api/types.ts LidarrSearchResult` /
- * `flutter_client/lib/models/lidarr.dart LidarrSearchResult`.
+ * the Flutter client's `LidarrSearchResult`.
 *
 * `inLibrary` and `requested` let the UI greyout rows the user can't
 * act on (already imported / already awaiting review). All defaults
@@ -9,8 +9,7 @@ import kotlinx.serialization.Serializable

 /**
 * Wire shapes for `POST /api/events`. The endpoint multiplexes four
- * variants on the `type` discriminator field, mirroring
- * `flutter_client/lib/api/endpoints/events.dart`.
+ * variants on the `type` discriminator field.
 *
 * play_started returns the server-assigned play_event_id (nullable —
 * server may suppress under certain conditions); the other three
@@ -5,9 +5,8 @@ import kotlinx.serialization.Serializable

 /**
 * Wire shape of `GET /api/home/index` — five flat slices of entity-ID
- * strings, one per Home section. Mirrors
- * `flutter_client/lib/models/home_index.dart` (and the server's
- * `internal/api/types.go HomeIndexPayload`).
+ * strings, one per Home section. Mirrors the server's
+ * `HomeIndexPayload` in `internal/api/types.go`.
 *
 * Section name implies entity type; no per-entry type tag is needed:
 *   - recentlyAddedAlbums  → album
@@ -5,8 +5,7 @@ import kotlinx.serialization.Serializable

 /**
 * Wire shape for `GET /api/me` and the return value of
- * `PUT /api/me/profile`. Mirrors
- * `flutter_client/lib/models/my_profile.dart`:
+ * `PUT /api/me/profile`. Two things the shape assumes:
 *   - `display_name` and `email` are nullable; server returns null
 *     when the user hasn't set them yet (registration only requires
 *     a username).
@@ -5,7 +5,7 @@ import kotlinx.serialization.Serializable

 /**
 * One row of `GET /api/quarantine/mine`. Mirrors
- * `flutter_client/lib/models/quarantine_mine.dart QuarantineMineRow`
+ * the Flutter client's `QuarantineMineRow`
 * (web `LidarrQuarantineMineRow`).
 *
 * Reason values: `bad_rip` / `wrong_file` / `wrong_tags` / `duplicate`
@@ -7,7 +7,7 @@ import kotlinx.serialization.Serializable
 * Wire shape of `requestView` from `internal/api/requests.go` — the
 * row returned by both `GET /api/requests` (caller's own requests) and
 * `GET /api/admin/requests` (cross-user admin view). Mirrors
- * `flutter_client/lib/models/admin_request.dart AdminRequest`.
+ * the Flutter client's `AdminRequest`.
 *
 * Status values: `pending` / `approved` / `rejected` / `completed` /
 * `failed`. Kind values: `artist` / `album` / `track`.
@@ -5,7 +5,7 @@ import kotlinx.serialization.Serializable

 /**
 * Wire shape for `TrackRef` as the server emits it. Mirrors
- * `flutter_client/lib/models/track.dart`'s `TrackRef.fromJson`
+ * the Flutter client's `TrackRef.fromJson`
 * field-for-field; the keys are snake_case because the server is Go
 * (json:"album_id" etc.).
 *
@@ -25,7 +25,7 @@ import javax.inject.Singleton
 * Pre-downloads the next-N tracks in the queue into the shared Media3
 * [androidx.media3.datasource.cache.SimpleCache] so a skip-forward or
 * natural advance plays from disk instead of waiting on a fresh HTTP
- * connection. Mirrors the Flutter `Prefetcher` (cache/prefetcher.dart):
+ * connection. Behaviour:
 * watches the player's current track, walks forward by
 * [com.fabledsword.minstrel.cache.audiocache.CacheSettings.prefetchWindow]
 * tracks, and pins each one. Idempotent — `CacheWriter` is a no-op when
@@ -23,7 +23,7 @@ private const val DEBOUNCE_MS = 2_000L
 * operator never finds out the track is bad and the next user hits
 * the same wall.
 *
- * The snackbar text mirrors Flutter's `playback_error_reporter.dart`:
+ * The snackbar text:
 * collect [PlayerController.playbackErrorEvents], debounce in a 2s
 * window, emit "Couldn't play 'X' — skipping" for a single error or
 * "Skipped N unplayable tracks" when a burst lands inside the window.
@@ -3,8 +3,7 @@ package com.fabledsword.minstrel.player
 import com.fabledsword.minstrel.models.TrackRef

 /**
- * Cycle on the repeat button: off → all → one → off. Mirrors
- * `AudioServiceRepeatMode` in flutter_client and maps directly to
+ * Cycle on the repeat button: off → all → one → off. Maps directly to
 * the three Media3 `Player.REPEAT_MODE_*` int constants.
 */
 enum class RepeatMode { OFF, ALL, ONE }
@@ -15,8 +15,7 @@ import javax.inject.Singleton

 /**
 * Persists the player's last queue + position to Room so a torn-down
- * session can resume on next app launch. Mirrors
- * `flutter_client/lib/cache/resume_controller.dart`.
+ * session can resume on next app launch.
 *
 * Subscribes to [PlayerController.uiState] in init; persists when the
 * (track-id, queueIndex) changes — captures real session transitions
@@ -30,8 +30,8 @@ private const val GRADIENT_TWEEN_MS = 600
 * The held color is NOT reset when [coverUrl] changes — it stays on
 * the previous track's dominant until the new palette resolves, so the
 * gradient tweens old→new directly instead of dipping toward the
- * fallback mid-swap. Mirrors `now_playing_screen.dart`'s preload-then-
- * swap ("keep the previous dominant"); the cover image swaps smoothly
+ * fallback mid-swap — preload-then-swap, keeping the previous dominant
+ * until the new one resolves. The cover image swaps smoothly
 * via `CoverPrefetcher`, which warms the next track's bytes into Coil.
 *
 * Starts at [Color.Transparent] (cold mount) and resets to it only
@@ -55,8 +55,9 @@ private const val COVER_SIZE_DP = 48
 private const val SCRUBBER_ROW_HEIGHT_DP = 4

 // Upward flick speed (dp/s) that expands the bar into NowPlaying.
-// Mirrors player_bar.dart's 200 px/s threshold; expressed in dp and
-// converted via density so the gesture feels the same across screens.
+// The 200 px/s threshold carries over from the Flutter player bar,
+// expressed in dp and converted via density so the gesture feels the
+// same across screens.
 private const val SWIPE_UP_VELOCITY_DP = 200

@OptIn(ExperimentalSharedTransitionApi::class)
@@ -129,7 +130,7 @@ fun MiniPlayer(
        .collectAsStateWithLifecycle(initialValue = false)

    // Swipe up anywhere on the bar to expand into the full player —
-    // mirrors player_bar.dart. We only act on a clear upward flick
+    // We only act on a clear upward flick
    // (negative velocity past the threshold) so a slow tap-with-jitter
    // doesn't accidentally open the screen. The horizontal seek slider
    // keeps its own gestures; a vertical draggable only claims
@@ -371,9 +371,7 @@ private fun NowPlayingContent(
        TrackHeader(title = track.title, artist = track.artistName, album = track.albumTitle)
        Spacer(Modifier.height(24.dp))
        // Action row (like, shuffle, repeat, queue, kebab) sits ABOVE the
-        // scrubber — Flutter's _SecondaryControls placement
-        // (now_playing_screen.dart:464). Android previously had it below
-        // the transport row.
+        // scrubber. Android previously had it below the transport row.
        BottomActionsRow(
            navController = navController,
            track = track,
@@ -88,7 +88,7 @@ class PlaylistsRepository @Inject constructor(
            // Reconcile: BuildSystemPlaylists rotates system-playlist
            // UUIDs every rebuild, so upsert alone leaves stale rows
            // whose detail fetch 404s ("That playlist no longer
-            // exists"). Mirrors playlists_provider.dart's deleteWhere.
+            // exists").
            playlistDao.replaceList(
                userId = userId,
                freshOwnedIds = wire.owned.map { it.id },
@@ -111,8 +111,7 @@ class PlaylistsRepository @Inject constructor(
            api.get(id)
        } catch (e: HttpException) {
            // Server says this playlist is gone — drop the stale cache
-            // row so the list stops showing it. Mirrors
-            // playlists_provider.dart's deleteWhere on detail failure.
+            // row so the list stops showing it.
            if (e.code() == HttpURLConnection.HTTP_NOT_FOUND) {
                playlistDao.deleteByIds(listOf(id))
            }
@@ -30,7 +30,6 @@ import com.fabledsword.minstrel.theme.FabledSwordFlatTokens
 /**
 * One playlist tile. Sized to match `AlbumCard` (176dp wide, 144dp
 * square cover) so they line up in the Home Playlists carousel.
- * Mirrors `flutter_client/lib/playlists/widgets/playlist_card.dart`.
 *
 * System playlists carry a small "For You" / "Discover" / etc. label
 * subtitle under the name (substituting for the artist-name line on
@@ -28,7 +28,6 @@ import com.fabledsword.minstrel.theme.FabledSwordFlatTokens

 /**
 * Placeholder tile for a system playlist that hasn't generated yet.
- * Mirrors `flutter_client/lib/playlists/widgets/playlist_placeholder_card.dart`.
 * Sized to match [PlaylistCard] so the Home Playlists row stays
 * visually consistent.
 *
@@ -231,7 +231,7 @@ private fun CancelConfirmDialog(
@Composable
 private fun KindAvatar(kind: String) {
    // Flutter mapping: disc-3 for artist, library-big for album,
-    // music for track. Mirrors lib/requests/requests_screen.dart.
+    // music for track.
    val icon = when (kind) {
        "artist" -> Lucide.Disc3
        "album" -> Lucide.LibraryBig
@@ -15,9 +15,6 @@ import androidx.compose.ui.unit.dp

 /**
 * Labeled horizontal-scroll section used throughout the Home screen.
- * Mirrors `flutter_client/lib/library/widgets/horizontal_scroll_row.dart`
- * — a Fraunces section title at 16dp gutter, then a horizontal LazyRow
- * with the same gutter and 8dp inter-item spacing.
 *
 * Pass empty `title` to render a continuation row directly under a
 * previously-titled one (used by Rediscover when it has both album and
@@ -24,10 +24,7 @@ import kotlinx.coroutines.launch

 /**
 * Always-visible circular play button overlaid on Home tile cover art
- * (AlbumCard / ArtistCard / PlaylistCard). Mirrors
- * `flutter_client/lib/library/widgets/play_circle_button.dart`: 44dp
- * accent-colored disc, parchment Play icon, drop shadow, self-managed
- * loading spinner.
+ * (AlbumCard / ArtistCard / PlaylistCard).
 *
 * [onPlay] is a suspend lambda so the caller can await the fetch-and-
 * queue setup. While it runs, the icon is swapped for a spinner and
@@ -54,8 +54,6 @@ val ShellContentWindowInsets: WindowInsets = WindowInsets(0, 0, 0, 0)
 * its own Scaffold's snackbar host as well; this one is the shell-
 * wide catch-all for events that outlive a single screen).
 *
- * Mirrors the Flutter `_ShellWithPlayerBar` (lib/shared/routing.dart).
- *
 * Top-level routes (Home / Library / Search / Discover / Playlists /
 * Settings / Admin / detail screens) wrap themselves with this.
 * Full-screen routes (NowPlaying / Queue / ServerUrl / Login)
@@ -8,7 +8,7 @@ import androidx.compose.runtime.Composable
 import androidx.compose.runtime.CompositionLocalProvider

 /**
- * The Flutter theme's `ColorScheme` role mapping (theme_data.dart):
+ * The `ColorScheme` role mapping:
 *   primary           = accent (forest-teal) — same both modes
 *   onPrimary         = onAction
 *   surface           = iron
@@ -10,9 +10,11 @@ package api
 // pgtype.Timestamptz / Date into strings, mirroring the pattern
 // playlistRowView already established for /api/playlists.
 //
-// Field names match flutter_client/lib/cache/sync_controller.dart's
-// _*FromJson helpers exactly. Adding a field server-side requires a
-// matching read in the Flutter helper or it'll be silently dropped.
+// Field names match what the Android client deserialises in
+// models/wire/SyncResponseWire.kt (Sync{Artist,Album,Track}Wire) exactly.
+// Adding a field server-side requires a matching @SerialName there or it is
+// silently dropped — kotlinx.serialization ignores unknown keys, so the
+// failure is a missing value at runtime, not an error at parse time.

 import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
@@ -11,9 +11,11 @@ import (

 // These tests pin the wire-format keys for /api/library/sync upserts.
 // Without them, sqlc model field-name drift or accidental
-// `json.Marshal(rawStruct)` regressions would silently break the
-// Flutter client (which reads snake_case keys via _*FromJson helpers
-// in flutter_client/lib/cache/sync_controller.dart).
+// `json.Marshal(rawStruct)` regressions would silently break the Android
+// client, which reads these snake_case keys via @SerialName in
+// models/wire/SyncResponseWire.kt. "Silently" is the operative word:
+// kotlinx.serialization skips unknown keys, so a renamed field arrives as
+// a default value rather than an error.

 // validUUID is a deterministic test UUID — not a real value, just
 // something that pgtype.UUID.Valid will accept.