Flixy heißt ab hier Halo

Reine Umbenennung, kein Verhalten geändert — bewusst als eigener Commit,
damit „umbenannt" und „umgebaut" im Nachhinein auseinanderzuhalten sind.

712 mal `Flixy`, 778 mal `flixy`, 7 mal `FLIXY` in 169 Dateien, dazu 25
Pfade. Ziele: `Halo`, `HaloTV`, `HaloTopShelf`, `HaloUITests`, `HaloKit` mit
`HaloDesign`, `HaloDownloads`, `HaloPlayback` und `HaloProbe`. `MediaKit`,
`JellyfinKit` und `DownloadWidget` tragen den Namen nicht und bleiben.

`docs/superpowers/specs/` ist ausgenommen. Datierte Entwurfsdokumente sind
ein Protokoll getroffener Entscheidungen; sie nachträglich umzuschreiben
hiesse, die Vergangenheit zu glätten.

**Die Bundle-ID wandert mit** — ausdrücklich so gewollt, mit bekanntem Preis:
`com.scarriffleservices.halo` ist für iOS eine *andere* App. Die installierte
Fassung bleibt daneben stehen, mit Downloads und Anmeldung in ihrem Container;
Halo startet leer. Einmal neu anmelden, heruntergeladene Folgen einmal neu
laden. Dasselbe gilt für die App-Gruppe, die sich TV-App und Top Shelf teilen.

**Eine Folge davon, die beim Entscheiden noch nicht auf dem Tisch lag:** der
Aufräumschritt aus dem vorigen Commit kommt an die alten Plex-Token nicht mehr
heran. Der Schlüsselbund grenzt nach Team und Bundle-Kennung ab — was unter
`…flixy` liegt, ist für `…halo` unerreichbar. Erledigt wird es trotzdem, nur
anders: **die alte App löschen.** iOS räumt deren Schlüsselbund-Einträge beim
Deinstallieren mit ab. Der Code bleibt stehen, weil er für jeden Stand vor
dieser Umbenennung richtig ist und im Jahr einen Startvergleich kostet.

Die Projektdatei ist aus `project.yml` neu erzeugt, der alte Ordner gelöscht
statt umbenannt — sie steht ohnehin nicht im Repo.

Das Verzeichnis des Repos selbst heißt weiter `Flixy`; das umzubenennen ist
ein Handgriff ausserhalb des Projekts.

368 Tests grün. iOS und tvOS bauen.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Packages/HaloKit/Sources/MediaKit/MediaBackend.swift

@@ -0,0 +1,251 @@
+import Foundation
+
+/// Was ein Server können muss, damit die App mit ihm arbeiten kann.
+///
+/// Der Vertrag ist bewusst schmal. Alles, was nur ein Server kann — Plex' PIN-
+/// Anmeldung, Jellyfins Verwaltung, die Eigenheiten des Programmführers —
+/// steht **nicht** hier, sondern als eigene Fähigkeit. Ein gemeinsamer Nenner,
+/// der alles umfasst, wäre kein Nenner mehr.
+public protocol MediaBackend: Sendable {
+    /// Wie der Server heißt, so wie er sich selbst nennt.
+    nonisolated var serverName: String { get }
+    /// Wer dieser Server ist — für alles, was ihn über einen Start hinaus
+    /// wiedererkennen muss.
+    ///
+    /// **Nicht der Name.** Zwei Server dürfen „Medien" heißen, und derselbe
+    /// Server darf umbenannt werden. Was hier steht, ist so gewählt, dass es
+    /// beides überlebt und beim nächsten Start noch gleich lautet. Es ist
+    /// eine Kennung und geht nirgends an die Oberfläche.
+    nonisolated var identity: String { get }
+    /// Was dieser Server darüber hinaus beherrscht.
+    nonisolated var capabilities: Set<BackendCapability> { get }
+
+    // MARK: - Blättern
+
+    func libraries() async throws(MediaBackendError) -> [MediaLibrary]
+    func homeRows() async throws(MediaBackendError) -> [MediaRowGroup]
+    func items(
+        inLibrary library: MediaLibrary,
+        query: MediaQuery,
+        offset: Int,
+        limit: Int
+    ) async throws(MediaBackendError) -> MediaPage
+    func item(id: String) async throws(MediaBackendError) -> MediaItem
+    /// In welcher Mediathek ein Titel liegt.
+    ///
+    /// **Warum das eine Frage ist.** Ein Titel weiss es nicht von selbst: er
+    /// kennt seinen unmittelbaren Vorgesetzten — bei einer Folge die Staffel,
+    /// bei einem Film die Mediathek — und mehr nicht. Wer die Mediathek einer
+    /// Folge wissen will, muss die Kette hinaufgehen, und das ist eine
+    /// Serveranfrage.
+    ///
+    /// Deshalb steht sie hier als eigene Frage und nicht als Feld an
+    /// `MediaItem`: sie wird selten gebraucht, kostet etwas, und ein Feld,
+    /// das meistens `nil` ist, verschweigt genau das.
+    ///
+    /// `nil`, wenn der Server es nicht sagen kann — dann fällt die Ebene weg,
+    /// statt zu raten.
+    func libraryID(for item: MediaItem) async -> String?
+    func children(of id: String) async throws(MediaBackendError) -> [MediaItem]
+    func search(_ text: String, limit: Int) async throws(MediaBackendError) -> [MediaRowGroup]
+    /// Die möglichen Werte eines Filters, etwa alle Genres einer Mediathek.
+    func filterOptions(
+        inLibrary library: MediaLibrary,
+        field: MediaQuery.Field
+    ) async throws(MediaBackendError) -> [MediaFilterOption]
+    /// Alle Folgen einer Serie, über alle Staffeln hinweg.
+    ///
+    /// **Als eigene Frage, weil der allgemeine Weg zu teuer ist.** Staffeln
+    /// holen und dann jede Staffel einzeln kostet bei zwölf Staffeln
+    /// dreizehn Anfragen — für einen Klick auf eine Kachel ist das zu viel.
+    /// Ein Server, der es in einer Anfrage kann, soll das dürfen.
+    func episodes(inSeries id: String) async throws(MediaBackendError) -> [MediaItem]
+    /// Die nächste Folge nach dieser, sofern es eine gibt.
+    func nextEpisode(after item: MediaItem) async throws(MediaBackendError) -> MediaItem?
+
+    // MARK: - Bilder
+
+    /// Ein Bild in der gewünschten Größe.
+    ///
+    /// `nonisolated`, weil die Adresse ohne Netzzugriff entsteht und der
+    /// Systemplayer sie ohne Kopfzeilen abruft — der Token steckt deshalb in
+    /// der Adresse selbst.
+    nonisolated func artworkURL(path: String?, width: Int, height: Int) -> URL?
+    nonisolated func rawImageURL(path: String?) -> URL?
+
+    // MARK: - Herunterladen
+
+    /// Die Adresse, unter der eine Datei unverändert zu holen ist.
+    nonisolated func downloadURL(for file: MediaFile) -> URL?
+
+    /// Die Adresse für eine verkleinerte Fassung.
+    ///
+    /// `nil`, wenn der Server das nicht anbietet — dann bleibt nur das
+    /// Original, und die Oberfläche soll die Wahl gar nicht erst zeigen.
+    nonisolated func compressedDownloadURL(
+        itemID: String,
+        versionIndex: Int,
+        maximumBitrate: Int,
+        resolution: String?
+    ) -> URL?
+
+    /// Die Adresse für dieselbe Datei in einer **anderen Schachtel**.
+    ///
+    /// Gemeint ist Umpacken, nicht Umrechnen: dieselben Ströme, eine Hülle,
+    /// die der Systemplayer öffnen kann. Nötig für Dateien, die offline sonst
+    /// unspielbar wären — auf dem Gerät gibt es keinen Server mehr, der
+    /// nachträglich helfen könnte.
+    ///
+    /// `nil`, wenn der Server das nicht anbietet. Dann bleibt das Original,
+    /// und der Titel ist offline nur so gut wie der Systemplayer.
+    ///
+    /// **Mit Spurnummern, weil beim Umpacken eine Wahl ansteht.** Der Server
+    /// legt in die neue Hülle genau eine Tonspur und höchstens einen
+    /// Untertitel. Welche, entscheidet der Aufrufer — offline lässt sich das
+    /// nicht nachholen.
+    nonisolated func remuxDownloadURL(
+        itemID: String,
+        versionIndex: Int,
+        audioStreamIndex: Int?,
+        subtitleStreamIndex: Int?
+    ) -> URL?
+
+    // MARK: - Abspielen
+
+    /// Lässt den Server eine Wiedergabe vorbereiten und nennt die Adresse.
+    ///
+    /// Wirft mit der Begründung des Servers, wenn er ablehnt. Genau daran hing
+    /// beim Live-TV tagelang alles: der Server hatte im Klartext gesagt, warum
+    /// er nicht mitspielt, und die Antwort wurde weggeworfen.
+    func preparePlayback(_ intent: PlaybackIntent) async throws(MediaBackendError) -> PlaybackTarget
+
+    /// Beendet, was der Server für diese Wiedergabe angelegt hat.
+    ///
+    /// Ohne dieses Signal rechnet ein Transcoder minutenlang weiter, obwohl
+    /// niemand mehr zusieht.
+    func endPlayback(sessionID: String) async
+
+    /// Meldet, wo man gerade steht.
+    ///
+    /// Wirft nicht: eine verlorene Meldung kostet ein paar Sekunden
+    /// Fortschritt, und dafür mitten im Film eine Fehlermeldung zu zeigen
+    /// wäre die schlechtere Hälfte des Tauschs.
+    func reportProgress(_ report: PlaybackReport) async
+
+    // MARK: - Zustand melden
+
+    func markWatched(id: String) async throws(MediaBackendError)
+    func markUnwatched(id: String) async throws(MediaBackendError)
+    /// Nimmt einen Titel aus „Weiterschauen", ohne ihn als gesehen zu melden.
+    ///
+    /// **Der Fall, für den es sonst nichts gibt.** Nach einer halben Stunde
+    /// keine Lust mehr — der Film ist weder gesehen noch ungesehen, er soll
+    /// nur nicht ewig weiter oben stehen. „Als gesehen markieren" wäre dafür
+    /// eine Lüge, „als ungesehen" tut nichts: der Fortschritt bleibt.
+    ///
+    /// **Der ganze Titel, nicht nur seine Kennung.** Jellyfin kennt dafür
+    /// keinen eigenen Weg; dort wird das Benutzerdatenblatt geschrieben, und
+    /// darin stehen auch „gesehen" und „Favorit". Wer sie nicht mitschickt,
+    /// löscht sie — und der Aufrufer hat sie ohnehin zur Hand.
+    func removeFromContinueWatching(_ item: MediaItem) async throws(MediaBackendError)
+    func setFavourite(_ isFavourite: Bool, id: String) async throws(MediaBackendError)
+    func rate(id: String, rating: Int) async throws(MediaBackendError)
+    func refreshLibrary(_ library: MediaLibrary) async throws(MediaBackendError)
+}
+
+/// Was ein Server über das Nötigste hinaus kann.
+///
+/// Abgefragt statt vorausgesetzt: Plex kennt keine Favoriten, Jellyfin keine
+/// Plex-Empfänger, und eine Oberfläche, die Knöpfe für Dinge zeigt, die der
+/// Server nicht kann, ist schlimmer als eine, die sie weglässt.
+public enum BackendCapability: String, Sendable, Hashable {
+    case liveTV
+    /// Aufnehmen und Vormerken — nicht dasselbe wie `liveTV`.
+    ///
+    /// Plex kann Sender zeigen und einschalten, aber in dieser App nichts
+    /// aufnehmen; Jellyfin kann beides. Eine Fähigkeit für beides zusammen
+    /// hieße, entweder Plex Live-TV wegzunehmen oder einen Knopf zu zeigen,
+    /// der dort nichts tut.
+    case liveTVRecordings
+    case favourites
+    case ratings
+    case libraryScan
+    /// Die Verwaltung des Servers aus der App heraus.
+    case administration
+    case transcoding
+}
+
+/// Ein Ausschnitt aus einer Mediathek.
+///
+/// „Seite" ist hier eine technische Portion, **keine Seite in der Oberfläche**.
+/// Die Mediathek ist eine einzige lange Liste, die nachlädt, sobald man sich
+/// dem Ende nähert — Blättern mit „weiter zu Seite 2" gehört nicht in eine
+/// Mediathek, in der man stöbert.
+public struct MediaPage: Sendable, Equatable {
+    public let items: [MediaItem]
+    /// Ab welcher Stelle dieser Ausschnitt beginnt.
+    public let offset: Int
+    /// Wie viele es insgesamt gibt — Grundlage fürs Nachladen.
+    public let totalCount: Int
+
+    public init(items: [MediaItem], offset: Int = 0, totalCount: Int) {
+        self.items = items
+        self.offset = offset
+        self.totalCount = totalCount
+    }
+
+    public var hasMore: Bool { offset + items.count < totalCount }
+    public var nextOffset: Int { offset + items.count }
+}
+
+public extension MediaBackend {
+    /// Vorgabe: der Server kann es nicht.
+    ///
+    /// So muss nicht jeder Server eine Adresse erfinden, die es bei ihm nicht
+    /// gibt — und wer es anbietet, sagt es ausdrücklich.
+    ///
+    /// **Mit Spurnummern, weil beim Umpacken eine Wahl ansteht.** Der Server
+    /// legt in die neue Hülle genau eine Tonspur und höchstens einen
+    /// Untertitel. Welche, entscheidet der Aufrufer — offline lässt sich das
+    /// nicht nachholen.
+    nonisolated func remuxDownloadURL(
+        itemID: String,
+        versionIndex: Int,
+        audioStreamIndex: Int?,
+        subtitleStreamIndex: Int?
+    ) -> URL? { nil }
+
+    /// Der allgemeine Weg: Staffeln, dann je Staffel die Folgen.
+    ///
+    /// Langsam, aber überall gültig — wer es besser kann, überschreibt es.
+    ///
+    /// **Ohne Sortieren und ohne Filtern.** Beides ist Sache von
+    /// `EpisodeSelection`, und es zweimal zu tun hiesse, dass die beiden
+    /// irgendwann auseinanderlaufen.
+    func episodes(inSeries id: String) async throws(MediaBackendError) -> [MediaItem] {
+        let staffeln = try await children(of: id)
+        var folgen: [MediaItem] = []
+        for staffel in staffeln {
+            folgen += (try? await children(of: staffel.id)) ?? []
+        }
+        return folgen
+    }
+
+    /// Ohne eigene Antwort keine Mediathek.
+    ///
+    /// Plex beantwortet das heute nicht, und eine falsche Antwort wäre
+    /// schlechter als keine: sie stellte die Sprache einer fremden Mediathek
+    /// über den allgemeinen Wunsch.
+    func libraryID(for item: MediaItem) async -> String? { nil }
+}
+
+/// Ein möglicher Wert für einen Filter.
+public struct MediaFilterOption: Sendable, Equatable, Identifiable {
+    public let id: String
+    public let title: String
+
+    public init(id: String, title: String) {
+        self.id = id
+        self.title = title
+    }
+}