fix: restore Prairie features dropped by upstream syncs and add an invariant guard

.github/workflows/prairie-invariants.yml

@@ -0,0 +1,28 @@
+name: Prairie invariants
+
+# Build-free tripwire for Prairie-only code that upstream Silo syncs have
+# silently deleted or unwired before (Live TV entries, Quick Connect, the
+# connect list, trickplay, image-format header). Unfiltered so it runs on
+# every PR, including a sync that only touches files it resolves to upstream.
+# See docs/upstream-sync.md.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  prairie-invariants:
+    name: Prairie invariants
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Check Prairie invariants
+        run: scripts/check-prairie-invariants.sh

.gitignore

@@ -66,6 +66,7 @@ Thumbs.db
 docs/*
 !docs/tvos-focus.md
 !docs/mac-builder.md
+!docs/upstream-sync.md
 !docs/tvos-player/
 docs/tvos-player/*
 !docs/tvos-player/aetherengine-replacement-spec.md

docs/upstream-sync.md

@@ -0,0 +1,44 @@
+# Syncing upstream Silo into Prairie Apple
+
+Prairie Apple is an AGPL fork of `Silo-Server/silo-apple`. Upstream syncs are
+routine, and they are also the main way Prairie loses work. A conflicted file
+resolved wholesale to upstream deletes Prairie's hunks, and the code often
+still compiles because the Prairie type survives while nothing calls it.
+Past losses: the first-run connect list (`ConnectServerListView`), the iOS
+Quick Connect and update-status rows, the `X-Prairie-Image-Formats` header on
+API requests, iOS trickplay scrub tiles, and Silo's diagnostics host coming
+back.
+
+## Rules
+
+- Sync on a `sync/upstream-<date>` branch with a real `git merge upstream/main`
+  and land it with **"Create a merge commit"**. Never squash; it drops upstream
+  ancestry and the next sync re-conflicts everything.
+- **A sync PR merges only with CI green**, including the macOS `Apple
+  regression` and `Unit Tests` jobs. A failing test after a sync usually means
+  Prairie code was dropped while its test was kept.
+- `Prairie invariants` (`scripts/check-prairie-invariants.sh`) must pass. If it
+  fails, restore the code. Do not edit the manifest to make it pass.
+
+## After resolving conflicts
+
+1. Rebrand fallout: `SiloAPI` → `PrairieAPI`, `silo*` colors and theme names →
+   `prairie*`, `X-Silo-*` → `X-Prairie-*`, `siloserver.org` hosts →
+   `prairieserver.org`. Keep wire tokens the server and other clients share
+   (`x-silo-original`, `_silocast._tcp`, `_silopair._tcp`,
+   `silo-public-diagnostics-v1`) unless the server changes them.
+2. Hunk audit: for each Prairie PR, check its added lines still exist in the
+   merge result (`gh pr diff <n>`). Upstream moves files, so search the whole
+   tree, not only the original path.
+3. Reachability: every Prairie screen must still have a caller. Grep for
+   `LiveTVChannelListView(`, `QuickConnectView()`, `ConnectServerListView(`.
+   A view type with no call site means lost wiring.
+4. New upstream tests that assert Silo strings or hosts need the Prairie value.
+5. Run `scripts/check-prairie-invariants.sh` and `scripts/ci/check-no-api-v1.sh`
+   locally; both run on Linux.
+
+## When you restore something a sync dropped
+
+Add an anchor for it to `scripts/prairie-invariants.txt` in the same PR: the
+file, the minimum number of matches, a regex on a stable identifier, and where
+it came from. That is what stops the next sync from deleting it again.

iosApp/Tests/HostedDiagnosticsAPITests.swift

@@ -9,7 +9,7 @@ final class HostedDiagnosticsAPITests: XCTestCase {
     func testDefaultCollectorSessionHasNoSharedCookiesOrCredentials() throws {
         XCTAssertEqual(
             HostedDiagnosticsAPI.defaultBaseURL,
-            try XCTUnwrap(URL(string: "https://diagnostics.siloserver.org"))
+            try XCTUnwrap(URL(string: "https://diagnostics.prairieserver.org"))
         )
 
         let session = HostedDiagnosticsAPI.makeIsolatedSession()

iosApp/iosApp/ContentView.swift

@@ -656,11 +656,15 @@ struct ContentView: View {
             }
 
         case .needsServerSetup:
-            #if os(tvOS)
-            TVServerSetupView(router: router)
-            #else
-            ServerSetupView(router: router)
-            #endif
+            // Prairie: first-run connect list (Saved + LAN discovery, PR #8).
+            // Manual URL entry, and tvOS phone pairing, are one push away via
+            // "Add manually" (`.serverSetup`).
+            NavigationStack(path: $router.path) {
+                ConnectServerListView(router: router)
+                    .navigationDestination(for: Route.self) { route in
+                        destinationView(for: route)
+                    }
+            }
 
         case .needsLogin:
             NavigationStack(path: $router.path) {

iosApp/iosApp/Downloads/DownloadSessionDelegate.swift

@@ -377,6 +377,7 @@ enum DownloadAuthHeaders {
             request.setValue(profileToken, forHTTPHeaderField: "X-Profile-Token")
         }
         AppleDeviceIdentity.current.applyHeaders(to: &request)
+        ImageFormats.apply(to: &request)
         return request
     }
 }

iosApp/iosApp/Networking/HTTPClient.swift

@@ -1251,6 +1251,8 @@ actor HTTPClient {
     ) {
         let device = AppleDeviceIdentity.current
         device.applyHeaders(to: &request)
+        // Prairie: one-time raster capability for artwork URLs (PR #23).
+        ImageFormats.apply(to: &request)
         let trace = credentials + [
             "device=\(device.platform)/\(device.clientFamily)",
             // Channel included deliberately: it is the only field that
@@ -1279,6 +1281,7 @@ actor HTTPClient {
             request.setValue(profileToken, forHTTPHeaderField: "X-Profile-Token")
         }
         AppleDeviceIdentity.current.applyHeaders(to: &request)
+        ImageFormats.apply(to: &request)
     }
 
     // MARK: - Response handling

iosApp/iosApp/Networking/HostedDiagnosticsAPI.swift

@@ -122,8 +122,10 @@ enum HostedDiagnosticsAPIError: Error, Equatable {
 }
 
 actor HostedDiagnosticsAPI {
+    /// Prairie's collector, matching Android `DEFAULT_HOSTED_DIAGNOSTICS_BASE_URL`.
+    /// Upstream syncs bring back Silo's host; never send Prairie reports there.
     static let defaultBaseURL: URL = {
-        guard let url = URL(string: "https://diagnostics.siloserver.org") else {
+        guard let url = URL(string: "https://diagnostics.prairieserver.org") else {
             fatalError("The hosted diagnostics URL must be valid.")
         }
         return url

iosApp/iosApp/Networking/PrairieAPI+LiveTV.swift

@@ -54,6 +54,13 @@ extension PrairieAPI {
         try await liveTVSend("DELETE", "/api/v1/livetv/sessions/\(try Self.encodePathSegment(sessionId))")
     }
 
+    /// Keep the tuner claimed while the player is open, including while
+    /// paused (no segment fetches). The server reclaims a session after 90 s
+    /// with neither a segment fetch nor a heartbeat.
+    func heartbeatLiveTVSession(sessionId: String) async throws {
+        try await liveTVSend("POST", "/api/v1/livetv/sessions/\(try Self.encodePathSegment(sessionId))/heartbeat")
+    }
+
     func liveTVRecordings(status: String? = nil) async throws -> [LiveTVRecording] {
         var query: [String: String] = [:]
         if let status, !status.isEmpty {

iosApp/iosApp/Pairing/PairingDeviceAPI.swift

@@ -149,6 +149,7 @@ struct PairingDeviceAPI: PairingDeviceAuthorizing {
         request.setValue("application/json", forHTTPHeaderField: "Accept")
         if let bearer { request.setValue("Bearer \(bearer)", forHTTPHeaderField: "Authorization") }
         AppleDeviceIdentity.current.applyHeaders(to: &request)
+        ImageFormats.apply(to: &request)
     }
 
     private func send<R: Decodable>(_ request: URLRequest, expectedStatus: Int) async throws -> R {

iosApp/iosApp/Screens/LiveTV/LiveTVPlayerView.swift

@@ -13,6 +13,10 @@ struct LiveTVPlayerView: View {
     @State private var didRelease = false
     @State private var itemStatusObservation: NSKeyValueObservation?
 
+    /// Heartbeat cadence. The server reclaims a session after 90 s with no
+    /// segment fetch or heartbeat, and a paused player fetches nothing.
+    static let heartbeatInterval: Duration = .seconds(30)
+
     var body: some View {
         ZStack(alignment: .topLeading) {
             Color.black.ignoresSafeArea()
@@ -43,6 +47,9 @@ struct LiveTVPlayerView: View {
         .task {
             await startPlaybackIfPossible()
         }
+        .task(id: session.sessionId) {
+            await keepSessionAlive()
+        }
         .onDisappear {
             itemStatusObservation?.invalidate()
             itemStatusObservation = nil
@@ -111,6 +118,22 @@ struct LiveTVPlayerView: View {
         return headers
     }
 
+    /// Heartbeats until the view goes away (task cancellation) or the
+    /// session is released. Failures are ignored: a missed beat is recovered
+    /// by the next one, and segment fetches also keep the session alive.
+    private func keepSessionAlive() async {
+        let sessionId = session.sessionId
+        while !Task.isCancelled {
+            do {
+                try await Task.sleep(for: Self.heartbeatInterval)
+            } catch {
+                return
+            }
+            guard !didRelease else { return }
+            try? await PrairieAPI.shared.heartbeatLiveTVSession(sessionId: sessionId)
+        }
+    }
+
     private func dismissAndRelease() {
         releaseSessionIfNeeded()
         player?.pause()

iosApp/iosApp/Screens/Player/iOS/MobilePlayerControls.swift

@@ -473,14 +473,15 @@ struct MobilePlayerControls: View {
             )
             .overlay(alignment: .topLeading) {
                 if viewModel.isScrubbing {
-                    let previewInset: CGFloat = viewModel.scrubPreviewImage == nil ? 80 : 102
+                    let hasArtwork = hasScrubPreviewArtwork
+                    let previewInset: CGFloat = hasArtwork ? 102 : 80
                     scrubPreviewBubble
                         .position(
                             x: min(
                                 max(width * progress, previewInset),
                                 max(width - previewInset, previewInset)
                             ),
-                            y: viewModel.scrubPreviewImage == nil ? -36 : -92
+                            y: hasArtwork ? -92 : -36
                         )
                         .transition(.opacity)
                         .allowsHitTesting(false)
@@ -513,14 +514,29 @@ struct MobilePlayerControls: View {
     /// Floating time + chapter readout pinned above the touch point while
     /// scrubbing. Presentation-only: reads the same `scrubPreviewTime` the
     /// seek machinery already maintains.
+    ///
+    /// Prairie: the server's trickplay sprite tile wins (PR #28, same as the
+    /// tvOS scrubber), then Aether's decoded frame, then the chapter still.
     private var scrubPreviewBubble: some View {
         VStack(spacing: 6) {
-            if let image = viewModel.scrubPreviewImage {
+            if let tile = scrubTrickplayTile {
+                TrickplayTileImage(tile: tile, displayWidth: 176)
+                    .clipShape(RoundedRectangle(cornerRadius: 9, style: .continuous))
+            } else if let image = viewModel.scrubPreviewImage {
                 Image(decorative: image, scale: 1)
                     .resizable()
                     .aspectRatio(contentMode: .fill)
                     .frame(width: 176, height: 99)
                     .clipShape(RoundedRectangle(cornerRadius: 9, style: .continuous))
+            } else if let chapterURL = scrubChapterThumbnailURL {
+                CachedAsyncImage(
+                    url: chapterURL,
+                    targetSize: CGSize(width: 176, height: 99),
+                    contentMode: .fill,
+                    placeholderStyle: .clear
+                )
+                .frame(width: 176, height: 99)
+                .clipShape(RoundedRectangle(cornerRadius: 9, style: .continuous))
             }
             Text(PlayerTimeFormatter.formatHMS(viewModel.scrubPreviewTime))
                 .font(.system(size: 19, weight: .bold))
@@ -538,6 +554,22 @@ struct MobilePlayerControls: View {
         .fixedSize()
     }
 
+    private var scrubTrickplayTile: TrickplayTilePreview? {
+        Trickplay.resolveTile(viewModel.trickplay, seconds: viewModel.scrubPreviewTime)
+    }
+
+    private var scrubChapterThumbnailURL: String? {
+        guard let url = viewModel.chapterThumbnailURL(at: viewModel.scrubPreviewTime),
+              !url.isEmpty else { return nil }
+        return url
+    }
+
+    private var hasScrubPreviewArtwork: Bool {
+        scrubTrickplayTile != nil
+            || viewModel.scrubPreviewImage != nil
+            || scrubChapterThumbnailURL != nil
+    }
+
     private func chapterTitle(at time: Double) -> String? {
         guard let chapter = viewModel.chapters.last(where: { $0.time <= time }) else { return nil }
         return chapter.title ?? "Chapter \(chapter.index + 1)"