Phase 1: Anmeldung, Bibliothek, Detailseiten, Hybrid-Player

Die Datenschicht:
- plex.tv-Anmeldung über das PIN-Verfahren, Token im Schlüsselbund
- Serversuche und Verbindungsauswahl nach Rang (lokal vor direkt vor
  Vermittlung), mit Abgleich der Server-Kennung gegen veraltete
  plex.direct-Adressen
- PlexServer als einzige Stelle, an der die App Endpunkte kennt:
  Mediatheken, Hubs, seitenweises Blättern mit Filtern, Metadaten,
  Staffeln/Folgen, Suche

Die Oberfläche:
- Startseite mit Aufmacher und den Reihen vom Server
- Mediathek als Raster oder Liste, mit Filter- und Sortierblatt
- Detailseiten für Filme, Folgen, Serien und Staffeln inkl. Besetzung,
  Fassungsauswahl und aufklappbaren technischen Angaben
- Suche mit gemerkten Anfragen
- Vollbildplayer mit eigenem Chrome

Der Player:
- AVPlayerEngine und VLCPlayerEngine hinter einem gemeinsamen Protokoll
- VLCKit liegt in einem eigenen Package (FlixyVLC), damit `swift test`
  in FlixyKit nicht das 920-MB-Binärpaket mitzieht

Am echten plex.tv geprüft: der Anmeldecode kommt an. Dabei fiel auf,
dass `strong=true` einen dreißigstelligen Code liefert, der sich bei
plex.tv/link nicht eintippen lässt — jetzt der kurze.

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

Packages/FlixyKit/Sources/PlexKit/Models/PlexItem.swift

@@ -6,7 +6,10 @@ import Foundation
 /// `type`. Das ist ungewohnt, aber praktisch: Suchergebnisse und Reihen auf
 /// der Startseite mischen die Arten, und ein gemeinsamer Typ erspart das
 /// Aufteilen bei jedem Abruf.
-public struct PlexItem: Sendable, Equatable, Codable, Identifiable {
+/// Nur `Decodable`: geschrieben wird dieser Typ nirgends. Der Offline-Bestand
+/// in Phase 3 bekommt ein eigenes SwiftData-Modell, weil er andere Felder
+/// braucht — lokaler Dateipfad, Ladezeitpunkt — und andere nicht.
+public struct PlexItem: Sendable, Equatable, Decodable, Identifiable {
     public enum Kind: String, Sendable, Codable {
         case movie, show, season, episode, clip, collection
     }
@@ -58,6 +61,15 @@ public struct PlexItem: Sendable, Equatable, Codable, Identifiable {
 
     public let media: [PlexMedia]
 
+    // Schlagwörter. Plex liefert sie nur bei der Einzelabfrage eines Titels
+    // mit, nicht in Listen — deshalb sind sie dort leer.
+    public let genres: [PlexTag]
+    public let directors: [PlexTag]
+    public let writers: [PlexTag]
+    /// Die Besetzung, mit Porträt und Rollennamen.
+    public let roles: [PlexTag]
+    public let markers: [PlexMarker]
+
     private enum CodingKeys: String, CodingKey {
         case ratingKey, key, guid, type, title, titleSort, summary, year, duration
         case contentRating, rating, audienceRating
@@ -67,6 +79,11 @@ public struct PlexItem: Sendable, Equatable, Codable, Identifiable {
         case viewCount, viewOffset, lastViewedAt, addedAt
         case leafCount, viewedLeafCount, childCount
         case media = "Media"
+        case genres = "Genre"
+        case directors = "Director"
+        case writers = "Writer"
+        case roles = "Role"
+        case markers = "Marker"
     }
 
     /// Von Hand geschrieben statt erzeugt, weil der erzeugte Decoder einen
@@ -112,6 +129,11 @@ public struct PlexItem: Sendable, Equatable, Codable, Identifiable {
         self.childCount = try values.decodeIfPresent(Int.self, forKey: .childCount)
 
         self.media = try values.decodeIfPresent([PlexMedia].self, forKey: .media) ?? []
+        self.genres = try values.decodeIfPresent([PlexTag].self, forKey: .genres) ?? []
+        self.directors = try values.decodeIfPresent([PlexTag].self, forKey: .directors) ?? []
+        self.writers = try values.decodeIfPresent([PlexTag].self, forKey: .writers) ?? []
+        self.roles = try values.decodeIfPresent([PlexTag].self, forKey: .roles) ?? []
+        self.markers = try values.decodeIfPresent([PlexMarker].self, forKey: .markers) ?? []
     }
 
     /// `ratingKey` ist serverweit eindeutig und eignet sich deshalb direkt
@@ -162,6 +184,7 @@ public struct PlexMediaContainer<Content: Decodable & Sendable>: Sendable, Decod
         case size, totalSize, offset, title1, title2
         case metadata = "Metadata"
         case directory = "Directory"
+        case hub = "Hub"
     }
 
     public init(from decoder: any Decoder) throws {
@@ -174,13 +197,15 @@ public struct PlexMediaContainer<Content: Decodable & Sendable>: Sendable, Decod
         self.title1 = try inner.decodeIfPresent(String.self, forKey: .title1)
         self.title2 = try inner.decodeIfPresent(String.self, forKey: .title2)
 
-        // `Metadata` bei Titeln, `Directory` bei Bibliotheken und Staffeln.
-        // Eine leere Mediathek liefert gar kein Feld — das ist kein Fehler,
-        // sondern bedeutet schlicht null Einträge.
+        // `Metadata` bei Titeln, `Directory` bei Mediatheken, `Hub` bei den
+        // Reihen der Startseite. Eine leere Mediathek liefert gar kein Feld —
+        // das ist kein Fehler, sondern bedeutet schlicht null Einträge.
         if let metadata = try inner.decodeIfPresent([Content].self, forKey: .metadata) {
             self.content = metadata
         } else if let directory = try inner.decodeIfPresent([Content].self, forKey: .directory) {
             self.content = directory
+        } else if let hub = try inner.decodeIfPresent([Content].self, forKey: .hub) {
+            self.content = hub
         } else {
             self.content = []
         }

Packages/FlixyKit/Sources/PlexKit/Models/PlexLibrary.swift

@@ -0,0 +1,106 @@
+import Foundation
+
+/// Eine Mediathek auf dem Server.
+public struct PlexLibrary: Sendable, Equatable, Decodable, Identifiable {
+    public enum Kind: String, Sendable, Codable {
+        case movie, show, artist, photo
+        /// Live-TV und Aufnahmen.
+        case livetv
+    }
+
+    /// Die Nummer des Abschnitts, als Zeichenkette. Steckt in fast jedem
+    /// weiteren Pfad.
+    public let key: String
+    public let title: String
+    public let type: String
+    public let uuid: String?
+    public let art: String?
+    public let thumb: String?
+    public let updatedAt: Int?
+
+    public var id: String { key }
+    public var kind: Kind? { Kind(rawValue: type) }
+
+    /// Ob Flixy diese Mediathek darstellen kann. Musik und Fotos sind laut
+    /// Plan nicht vorgesehen — sie erscheinen deshalb gar nicht erst in der
+    /// Seitenleiste, statt dort auf einen leeren Bildschirm zu führen.
+    public var isSupported: Bool {
+        kind == .movie || kind == .show
+    }
+
+    public init(
+        key: String,
+        title: String,
+        type: String,
+        uuid: String? = nil,
+        art: String? = nil,
+        thumb: String? = nil,
+        updatedAt: Int? = nil
+    ) {
+        self.key = key
+        self.title = title
+        self.type = type
+        self.uuid = uuid
+        self.art = art
+        self.thumb = thumb
+        self.updatedAt = updatedAt
+    }
+}
+
+/// Eine Reihe auf der Startseite.
+///
+/// Plex nennt sie „Hub" und liefert sie fertig zusammengestellt — Weiterschauen,
+/// Zuletzt hinzugefügt, Sammlungen. Die App muss diese Reihen also nicht selbst
+/// bauen, sondern nur darstellen.
+public struct PlexHub: Sendable, Equatable, Decodable, Identifiable {
+    /// Stabiler Bezeichner wie `home.continue` oder `movie.recentlyadded`.
+    /// Danach richtet sich die Sortierung in den Einstellungen.
+    public let hubIdentifier: String
+    public let title: String
+    public let type: String?
+    public let key: String?
+    public let size: Int?
+    /// Ob es mehr Einträge gibt, als die Reihe zeigt — Grundlage für ein
+    /// „Alle anzeigen" am Ende.
+    public let more: Bool
+    public let items: [PlexItem]
+
+    public var id: String { hubIdentifier }
+
+    private enum CodingKeys: String, CodingKey {
+        case hubIdentifier, title, type, key, size, more
+        case items = "Metadata"
+    }
+
+    public init(from decoder: any Decoder) throws {
+        let values = try decoder.container(keyedBy: CodingKeys.self)
+        self.title = try values.decode(String.self, forKey: .title)
+        // Ältere Serverfassungen liefern keinen `hubIdentifier`. Der Titel ist
+        // dann der einzige verfügbare Schlüssel — schlechter, aber besser als
+        // eine Antwort, die gar nicht lesbar ist.
+        self.hubIdentifier = try values.decodeIfPresent(String.self, forKey: .hubIdentifier) ?? title
+        self.type = try values.decodeIfPresent(String.self, forKey: .type)
+        self.key = try values.decodeIfPresent(String.self, forKey: .key)
+        self.size = try values.decodeIfPresent(Int.self, forKey: .size)
+        self.more = try values.decodeIfPresent(Bool.self, forKey: .more) ?? false
+        self.items = try values.decodeIfPresent([PlexItem].self, forKey: .items) ?? []
+    }
+
+    public init(
+        hubIdentifier: String,
+        title: String,
+        type: String? = nil,
+        key: String? = nil,
+        size: Int? = nil,
+        more: Bool = false,
+        items: [PlexItem] = []
+    ) {
+        self.hubIdentifier = hubIdentifier
+        self.title = title
+        self.type = type
+        self.key = key
+        self.size = size
+        self.more = more
+        self.items = items
+    }
+}

Packages/FlixyKit/Sources/PlexKit/Models/PlexTag.swift

@@ -0,0 +1,63 @@
+import Foundation
+
+/// Ein Schlagwort am Titel: Genre, Regie, Rolle, Land.
+///
+/// Plex gibt sie alle in derselben Form aus und unterscheidet nur über den
+/// Feldnamen. `role` ist dabei nur bei Besetzungseinträgen gefüllt und trägt
+/// den Namen der gespielten Figur.
+public struct PlexTag: Sendable, Equatable, Hashable, Decodable, Identifiable {
+    public let tagKey: String?
+    public let tag: String
+    public let role: String?
+    public let thumb: String?
+
+    private let rawID: Int?
+
+    /// Eigene Kennung statt `id` vom Server: Genres kommen ohne, und zwei
+    /// Einträge ohne Kennung würden in `ForEach` zusammenfallen.
+    public var id: String { tagKey ?? rawID.map(String.init) ?? tag }
+
+    private enum CodingKeys: String, CodingKey {
+        case rawID = "id"
+        case tagKey, tag, role, thumb
+    }
+
+    public init(from decoder: any Decoder) throws {
+        let values = try decoder.container(keyedBy: CodingKeys.self)
+        self.rawID = try values.decodeIfPresent(Int.self, forKey: .rawID)
+        self.tagKey = try values.decodeIfPresent(String.self, forKey: .tagKey)
+        self.tag = try values.decode(String.self, forKey: .tag)
+        self.role = try values.decodeIfPresent(String.self, forKey: .role)
+        self.thumb = try values.decodeIfPresent(String.self, forKey: .thumb)
+    }
+
+    public init(tag: String, role: String? = nil, thumb: String? = nil, tagKey: String? = nil) {
+        self.rawID = nil
+        self.tagKey = tagKey
+        self.tag = tag
+        self.role = role
+        self.thumb = thumb
+    }
+}
+
+/// Eine Sprungmarke in einer Datei: Intro oder Abspann.
+///
+/// Wird schon in Phase 1 mitgelesen, obwohl sie erst in Phase 2 ausgewertet
+/// wird — sie kostet nichts und erspart später eine zweite Anfrage.
+public struct PlexMarker: Sendable, Equatable, Decodable, Identifiable {
+    public let id: Int
+    public let type: String
+    /// In Millisekunden ab Beginn.
+    public let startTimeOffset: Int
+    public let endTimeOffset: Int
+
+    public var isIntro: Bool { type == "intro" }
+    public var isCredits: Bool { type == "credits" }
+
+    public init(id: Int, type: String, startTimeOffset: Int, endTimeOffset: Int) {
+        self.id = id
+        self.type = type
+        self.startTimeOffset = startTimeOffset
+        self.endTimeOffset = endTimeOffset
+    }
+}