v0.5.0 — Phase β-4 Media + Advanced Card-Types

Alle 7 Card-Types werden gerendert und können erstellt werden.
image-occlusion mit Touch-Drag-Mask-Editor (kein PencilKit — Server-
Schema erlaubt nur Rechtecke), audio-front mit AVAudioPlayer und
File-Picker.

- MediaUploadResponse-DTO, MaskRegion-Codable mit 0..1-Coordinates
- MaskRegions.parse/encode (1:1-Port aus cards-domain, Sortierung
  nach ID lexikographisch)
- CardFieldsBuilder.imageOcclusion mit stringified-JSON-mask_regions
  + audioFront
- CardsAPI.uploadMedia (Multipart, 25 MiB) + fetchMedia (streamed)
- MediaCache actor mit LRU 200 MB (contentModificationDate-Eviction)
- mediaCache Environment-Key
- RemoteImage + AudioPlayerButton SwiftUI-Views
- CardRenderer: imageOcclusion (Mask-Overlay über RemoteImage) +
  audioFront (AudioPlayerButton + back-Text auf Flip)
- MaskEditorView: Touch-Drag-Rechteck, Label-Edit, Delete
- CardEditorView erweitert: PhotosPicker für Image, fileImporter
  für Audio, Magic-Byte-MIME-Detection
- 6 neue Tests für MaskRegions (30 Total grün)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Sources/Core/API/CardsAPI.swift

@@ -54,6 +54,44 @@ actor CardsAPI {
         return try decoder.decode(DueReviewsResponse.self, from: data).total
     }
 
+    // MARK: - Media
+
+    /// `POST /api/v1/media/upload` — Multipart-Upload. Max 25 MiB.
+    /// Erlaubte MIMEs: image/*, audio/*, video/*.
+    func uploadMedia(data: Data, filename: String, mimeType: String) async throws -> MediaUploadResponse {
+        let boundary = "cards-native-\(UUID().uuidString)"
+        let body = makeMultipartBody(
+            file: data,
+            filename: filename,
+            mimeType: mimeType,
+            boundary: boundary
+        )
+        let (response, http) = try await transport.request(
+            path: "/api/v1/media/upload",
+            method: "POST",
+            body: body,
+            contentType: "multipart/form-data; boundary=\(boundary)"
+        )
+        try ensureOK(http, data: response)
+        return try decoder.decode(MediaUploadResponse.self, from: response)
+    }
+
+    /// `GET /api/v1/media/:id` — streamt das Media-File. Antwortet mit
+    /// raw bytes (kein JSON), Caller schreibt das auf Disk via MediaCache.
+    func fetchMedia(id: String) async throws -> Data {
+        let (data, http) = try await transport.request(path: "/api/v1/media/\(id)")
+        guard (200 ..< 300).contains(http.statusCode) else {
+            throw AuthError.serverError(status: http.statusCode, message: "media fetch failed")
+        }
+        return data
+    }
+
+    /// `DELETE /api/v1/media/:id` — Soft-Forget. (Endpoint heute nicht
+    /// implementiert serverseitig; Stub bleibt für späteren Use.)
+    func deleteMedia(id _: String) async throws {
+        throw AuthError.serverError(status: 501, message: "media delete not implemented on server")
+    }
+
     // MARK: - Deck-Mutations
 
     /// `POST /api/v1/decks` — Deck anlegen.
@@ -172,6 +210,28 @@ actor CardsAPI {
         return try encoder.encode(value)
     }
 
+    // MARK: - Multipart
+
+    private func makeMultipartBody(
+        file: Data,
+        filename: String,
+        mimeType: String,
+        boundary: String
+    ) -> Data {
+        var body = Data()
+        let lineBreak = "\r\n"
+        let header = """
+        --\(boundary)\(lineBreak)\
+        Content-Disposition: form-data; name="file"; filename="\(filename)"\(lineBreak)\
+        Content-Type: \(mimeType)\(lineBreak)\(lineBreak)
+        """
+        body.append(header.data(using: .utf8) ?? Data())
+        body.append(file)
+        body.append(lineBreak.data(using: .utf8) ?? Data())
+        body.append("--\(boundary)--\(lineBreak)".data(using: .utf8) ?? Data())
+        return body
+    }
+
     // MARK: - Helpers
 
     private func ensureOK(_ http: HTTPURLResponse, data: Data) throws {

Sources/Core/Domain/Media.swift

@@ -0,0 +1,103 @@
+import Foundation
+
+/// Response von `POST /api/v1/media/upload`.
+struct MediaUploadResponse: Decodable, Sendable {
+    let id: String
+    let url: String
+    let mimeType: String
+    let kind: MediaKind
+    let sizeBytes: Int
+    let originalFilename: String?
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case url
+        case mimeType = "mime_type"
+        case kind
+        case sizeBytes = "size_bytes"
+        case originalFilename = "original_filename"
+    }
+}
+
+enum MediaKind: String, Codable, Sendable {
+    case image
+    case audio
+    case video
+    case other
+}
+
+/// Image-Occlusion-Mask-Region.
+/// `mask_regions`-Feld ist ein JSON-Array-**String** in `fields`,
+/// nicht ein Object — Server-Schema-Constraint (`fields: Record<string,string>`).
+struct MaskRegion: Codable, Hashable, Sendable, Identifiable {
+    let id: String
+    let x: Double // 0..1 relativ
+    let y: Double
+    let w: Double
+    let h: Double
+    let label: String?
+
+    init(id: String, x: Double, y: Double, w: Double, h: Double, label: String? = nil) {
+        self.id = id
+        self.x = x
+        self.y = y
+        self.w = w
+        self.h = h
+        self.label = label
+    }
+}
+
+/// Helpers zum Parsen/Serialisieren von `mask_regions` als JSON-String.
+enum MaskRegions {
+    /// 1:1-Port aus `cards-domain/image-occlusion.ts:parseMaskRegions`.
+    /// Bei Parse- oder Schema-Fehler: leere Liste. Sortiert nach ID
+    /// (lexikographisch, gleich wie Server-Sortierung).
+    static func parse(_ json: String) -> [MaskRegion] {
+        guard let data = json.data(using: .utf8) else { return [] }
+        guard let regions = try? JSONDecoder().decode([MaskRegion].self, from: data) else { return [] }
+        return regions.sorted { $0.id < $1.id }
+    }
+
+    /// Sub-Index → Region (Sortier-Reihenfolge).
+    static func region(for json: String, subIndex: Int) -> MaskRegion? {
+        let all = parse(json)
+        return all.indices.contains(subIndex) ? all[subIndex] : nil
+    }
+
+    /// Anzahl Regionen → Anzahl Sub-Index-Reviews.
+    static func count(_ json: String) -> Int {
+        parse(json).count
+    }
+
+    /// Serialisiert eine Liste zu einem JSON-Array-String fürs `fields`-Feld.
+    static func encode(_ regions: [MaskRegion]) -> String {
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.sortedKeys]
+        guard let data = try? encoder.encode(regions) else { return "[]" }
+        return String(decoding: data, as: UTF8.self)
+    }
+}
+
+extension CardFieldsBuilder {
+    /// `image-occlusion`-Fields: `image_ref` (media_id) +
+    /// `mask_regions` (stringified JSON-Array) + optional `note`.
+    static func imageOcclusion(
+        imageRef: String,
+        regions: [MaskRegion],
+        note: String? = nil
+    ) -> [String: String] {
+        var fields: [String: String] = [
+            "image_ref": imageRef,
+            "mask_regions": MaskRegions.encode(regions),
+        ]
+        if let note, !note.isEmpty {
+            fields["note"] = note
+        }
+        return fields
+    }
+
+    /// `audio-front`-Fields: `audio_ref` (media_id) + `back` (Antwort-Text).
+    static func audioFront(audioRef: String, back: String) -> [String: String] {
+        ["audio_ref": audioRef, "back": back]
+    }
+}

Sources/Core/Sync/MediaCache.swift

@@ -0,0 +1,73 @@
+import Foundation
+import ManaCore
+
+/// Persistenter Disk-Cache für Cards-Media-Files. Bilder/Audio werden
+/// einmal vom Server geladen und danach lokal serviert — der Server
+/// setzt `Cache-Control: private, immutable`, das honorieren wir hier.
+///
+/// LRU-Verdrängung mit Soft-Limit (Default 200 MB).
+actor MediaCache {
+    private let root: URL
+    private let api: CardsAPI
+    private let maxBytes: Int
+
+    init(api: CardsAPI, maxBytes: Int = 200 * 1024 * 1024) {
+        self.api = api
+        self.maxBytes = maxBytes
+        let caches = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)[0]
+        root = caches.appendingPathComponent("cards-media", isDirectory: true)
+        try? FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+    }
+
+    /// Liefert die lokale URL eines Media-Files. Lädt vom Server, falls
+    /// nicht im Cache. Wirft `AuthError`, wenn der Download scheitert.
+    func localURL(for mediaId: String) async throws -> URL {
+        let target = root.appendingPathComponent(mediaId)
+        if FileManager.default.fileExists(atPath: target.path) {
+            try? FileManager.default.setAttributes([.modificationDate: Date.now], ofItemAtPath: target.path)
+            return target
+        }
+        let data = try await api.fetchMedia(id: mediaId)
+        try data.write(to: target, options: .atomic)
+        try? await pruneIfNeeded()
+        return target
+    }
+
+    /// Direktes Lesen — für UI-Komponenten, die `Data` brauchen (z.B. AVAudioPlayer).
+    func data(for mediaId: String) async throws -> Data {
+        try Data(contentsOf: try await localURL(for: mediaId))
+    }
+
+    /// LRU-Eviction: bei Überschreitung des Limits ältesten zuerst löschen.
+    private func pruneIfNeeded() async throws {
+        let resourceKeys: Set<URLResourceKey> = [.fileSizeKey, .contentModificationDateKey]
+        guard let items = try? FileManager.default.contentsOfDirectory(
+            at: root,
+            includingPropertiesForKeys: Array(resourceKeys)
+        ) else { return }
+
+        let withMeta = items.compactMap { url -> (url: URL, size: Int, date: Date)? in
+            let values = try? url.resourceValues(forKeys: resourceKeys)
+            guard let size = values?.fileSize, let date = values?.contentModificationDate else { return nil }
+            return (url, size, date)
+        }
+
+        let totalBytes = withMeta.reduce(0) { $0 + $1.size }
+        guard totalBytes > maxBytes else { return }
+
+        let sortedOldestFirst = withMeta.sorted { $0.date < $1.date }
+        var remaining = totalBytes
+        for item in sortedOldestFirst {
+            if remaining <= maxBytes { break }
+            try? FileManager.default.removeItem(at: item.url)
+            remaining -= item.size
+            Log.sync.info("MediaCache evicted \(item.url.lastPathComponent, privacy: .public) (\(item.size, privacy: .public)B)")
+        }
+    }
+
+    /// Wipe — für Sign-out o.ä.
+    func clear() {
+        try? FileManager.default.removeItem(at: root)
+        try? FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+    }
+}

Sources/Core/Sync/MediaEnvironment.swift

@@ -0,0 +1,15 @@
+import SwiftUI
+
+/// Environment-Key, der den shared `MediaCache` durch die View-Hierarchie
+/// reicht. App-Entrypoint setzt den Wert; Views lesen via
+/// `@Environment(\.mediaCache)`.
+private struct MediaCacheKey: EnvironmentKey {
+    static let defaultValue: MediaCache? = nil
+}
+
+extension EnvironmentValues {
+    var mediaCache: MediaCache? {
+        get { self[MediaCacheKey.self] }
+        set { self[MediaCacheKey.self] = newValue }
+    }
+}