cards-native/PLAN.md

# Plan — cards-native (SwiftUI Universal)

**Stand: 2026-05-13 — Phasen β-0 bis β-5 abgeschlossen.**
Alle 7 Card-Types + voller Marketplace (Explore/Browse/Subscribe)
+ TabBar + Universal-Link-Handling für `cardecky.mana.how/d/<slug>`.
35 Unit-Tests + 1 UI-Test grün.

Pflicht-Check für β-2: Endurance-Test auf realem Gerät (200+ Karten
mit Flugmodus zwischendurch) steht aus — Aufgabe für Till.

> **SOT:** `../mana/docs/playbooks/CARDS_NATIVE_GREENFIELD.md`.
> Dieses File ist die App-lokale Status-Spur, das Greenfield-Doc
> hat die ganze Architektur-Begründung.

## Aktueller Stand

✅ **β-0 — Setup (2026-05-12, Tag `v0.1.0`)**
- Repo-Skelett unter `git.mana.how/till/cards-native`
- `project.yml` mit Bundle-ID `ev.mana.cards`, ManaSwiftCore via
  `path: ../mana-swift-core`
- `AppConfig` als `ManaAppConfig`-Provider:
  - Auth: `https://auth.mana.how`
  - API: `https://cardecky-api.mana.how`
  - Keychain-Service: `ev.mana.cards`
- `CardsTheme.swift` mit forest-Werten (lokal nachgebaut aus
  `mana/packages/themes/src/variants/forest.css`)
- `LoginView` (Email/PW gegen mana-auth)
- 3 Unit-Tests (AppConfig)

✅ **β-5 — Marketplace (2026-05-13, Tag `v0.6.0`)**
- `PublicDeckEntry`, `PublicDeck`, `PublicDeckVersion`, `PublicDeckOwner`,
  `PublicDeckDetail`, `ExploreResponse`, `BrowseResponse`,
  `SubscribeResponse` Codable-DTOs mit snake_case
- `MarketplaceSort` Enum (recent/popular/trending) mit deutschen Labels
- `CardsAPI`: explore(), browseMarketplace(query:sort:language:),
  publicDeck(slug:), subscribe(slug:), unsubscribe(slug:)
- `MarketplaceStore` @Observable mit Explore-State + Browse-State
- `ExploreView` mit Featured + Trending Carousels, Browse-Link
- `BrowseView` mit Searchable + Sort-Picker + Liste
- `PublicDeckView` mit Header + Version + Owner + Subscribe-Button
  (Auto-Fork serverseitig, danach NavigationLink zum eigenen Deck)
- `PublicDeckCard` + `BrowseRow` Komponenten mit forest-Theme
- `RootView` → TabBar (Decks / Entdecken / Account) statt Single-View
- Universal-Link-Handler in `RootView` (onOpenURL + onContinueUserActivity):
  `https://cardecky.mana.how/d/<slug>` und `cards://d/<slug>` → Explore-Tab
  öffnet `PublicDeckView`
- `associated-domains: applinks:cardecky.mana.how` im entitlement
- 5 neue Marketplace-Decoding-Tests (35 Total grün)

**Wichtig:** Universal-Links funktionieren erst, wenn AASA-Endpoint
unter `cardecky.mana.how/.well-known/apple-app-site-association`
ausgeliefert wird — heute 404. Web-seitige Aufgabe.

✅ **β-4 — Media + Advanced Card-Types (2026-05-13, Tag `v0.5.0`)**
- `MediaUploadResponse` DTO + `MediaKind`-Enum
- `MaskRegion` Codable mit 0..1-Coordinates, `MaskRegions.parse/encode`-
  Helpers (1:1-Port aus `cards-domain/image-occlusion.ts` — Sortierung
  nach ID lexikographisch)
- `CardFieldsBuilder.imageOcclusion`, `.audioFront` mit korrekter
  `mask_regions`-Serialisierung als stringified JSON-Array
- `CardsAPI.uploadMedia(data, filename, mimeType)` mit Multipart
  (25 MiB max), `.fetchMedia(id)` für streamed bytes
- `MediaCache` actor mit LRU 200 MB (sortiert nach `contentModificationDate`)
- `mediaCache`-Environment-Key, im App-Entrypoint instantiiert
- `RemoteImage` View — authentifiziertes Image-Loading mit ProgressView
  + Failure-State
- `AudioPlayerButton` — AVAudioPlayer-Wrapper mit Play/Pause-Toggle,
  AVAudioSession-Setup für iOS
- `CardRenderer.imageOcclusionView`: AsyncImage + opake Maske über aktiver
  Region (Frontside), Label-Reveal auf Backside
- `CardRenderer.audioFrontView`: AudioPlayerButton + back-Text auf Flip
- `MaskEditorView`: Touch-Drag-to-Create-Rectangle, Liste mit Label-Edit
  + Delete, 0..1-Normalisierung beim Commit
- `CardEditorView` erweitert: PhotosPicker für Image, fileImporter für
  Audio, Magic-Byte-MIME-Detection (JPEG/PNG/GIF/WebP)
- 6 neue Tests für MaskRegions-Parse/Encode + Field-Builder (30 Total)

✅ **β-3 — Editor (2026-05-13, Tag `v0.4.0`)**
- `DeckCreateBody`, `DeckUpdateBody`, `CardCreateBody`, `CardUpdateBody`
  Encodable-Structs (snake_case via `CodingKeys`, nil-Felder werden
  weggelassen)
- `CardFieldsBuilder` mit Type-spezifischen Pflicht-Feld-Konstruktoren
- `CardsAPI`: createDeck/updateDeck/deleteDeck + createCard/updateCard/deleteCard
- `DeckEditorView` für Create + Edit in einer View (mode-switch),
  Color-Picker mit 8-Preset-Palette aus forest-Theme, Category-Picker
  (11 Kategorien mit deutschen Labels), Visibility-Segmented-Control
- `CardEditorView` mit Type-Picker (basic, basic-reverse, cloze,
  typing, multiple-choice) und dynamischen Feldern je Typ. Cloze-View
  zeigt Live-Cluster-Count und Hint-Syntax-Hinweis. image-occlusion
  und audio-front zeigen β-4-Placeholder
- `DeckDetailView` mit 4 Action-Buttons (Lernen, Karte hinzufügen,
  Bearbeiten, Löschen), Confirmation-Dialog für Delete
- DeckListView: "+"-Button im Toolbar (Leading), Sheet für Create
- 7 zusätzliche Encoding-Tests (24 Unit-Tests total)

✅ **β-2 — Study-Loop (2026-05-13, Tag `v0.3.0`)**
- `Card`, `Review`, `DueReview` Codable-DTOs, `CardType`-Enum (alle 7 Typen)
- `Rating`-Enum: `again | hard | good | easy` mit deutschen Labels
- `Cloze`-Helpers (extractClusterIds, subIndexCount, clusterId,
  renderPrompt, renderAnswer, hint) — 1:1-Port aus
  `cards/packages/cards-domain/src/cloze.ts`
- `CardsAPI.dueReviews(deckId:)`, `CardsAPI.gradeReview(...)` mit
  ISO8601-Encoder
- `PendingGrade` SwiftData-Model + `GradeQueue` für Offline-Submit
  (FIFO-Drain, originaler reviewedAt-Timestamp bleibt erhalten)
- `StudySession` als @Observable State-Machine
  (loading/studying/finished/failed)
- `CardRenderer`: basic, basic-reverse (sub-index-abhängig), cloze
  client-rendered. image-occlusion/audio-front/typing/multiple-choice
  zeigen Placeholder (β-3/β-4)
- `RatingBar` mit Haptic-Feedback (medium für again/hard/good,
  heavy für easy, soft beim Flip)
- `StudySessionView` vollbild aus DeckListView per NavigationLink
- 9 zusätzliche Tests (Cloze 8x, Review/DueReview-Decoding 3x)

✅ **β-1 — Decks lesen (2026-05-13, Tag `v0.2.0`)**
- `Deck`-Codable-DTO mit snake_case-CodingKeys, plus
  `DeckCategory`, `DeckVisibility`, `FsrsSettings`
- ISO8601-Date-Decoder mit Fractional-Seconds-Toleranz
- `CardsAPI.listDecks()`, `cardCount(deckId:)`, `dueCount(deckId:)`
- `CachedDeck` als SwiftData-Model mit `lastFetchedAt` (Offline-Read)
- `DeckListStore` orchestriert API + Cache, paralleles Counts-Fetching
  via TaskGroup
- `DeckListView` mit Pull-to-Refresh, Card/Due-Counts, deck.color-Streifen,
  Inbox-Banner für Marketplace-Forks
- `AccountView` mit Sign-out-Button
- iOS-Simulator-Build + Tests grün (6 Unit-Tests, 1 UI-Test)

## Phasen (Detail in Greenfield-Plan)

| Phase | Status | Inhalt |
|---|---|---|
| β-0 | ✅ 2026-05-12 | Setup, Login, API-Probe |
| β-1 | ✅ 2026-05-13 | Decks lesen, SwiftData-Cache, Pull-to-Refresh |
| β-2 | ✅ 2026-05-13 | Study-Loop, Offline-Grade-Queue (Endurance-Test offen) |
| β-3 | ✅ 2026-05-13 | Editor: Deck-CRUD + Card-Create (5 Types); Anki-Import auf β-3-ext verschoben |
| β-4 | ✅ 2026-05-13 | Media-Upload, image-occlusion (Touch-Mask-Editor), audio-front (AVAudioPlayer) |
| β-5 | ✅ 2026-05-13 | Marketplace (Explore/Browse/Subscribe) + TabBar + Universal-Link-Handler (AASA server-side pending) |
| β-6 | — | Native-Polish (Widgets, Notifications, Share-Extension) |
| β-7 | — | App-Store-Submission |

## Nächste Schritte für β-6 (Native-Polish)

Aus Greenfield-Plan-Sektion "Phase β-6":

1. WidgetKit-Extension (Small, Medium, Lock-Screen) mit Due-Count
2. UNUserNotificationCenter — tägliche Reminder zur konfigurierten Zeit
3. Siri-Shortcuts ("Karten lernen" → Default-Deck)
4. Share-Extension "Save as Card" für Safari/Mail
5. Keyboard-Shortcuts iPad/macOS (Space=flip, 1-4=Rating, J/K=next/prev)
6. App-Group `group.ev.mana.cards` für Widget-Daten-Sharing

## Notizen aus β-4

- **PencilKit für Mask-Editor explizit nicht genutzt.** Web macht
  Image-Occlusion-Masks per Touch-Drag-Rechteck (kein Freihand). Server-
  Schema (`MaskRegion = {id, x, y, w, h, label}`) erlaubt nur Rechtecke,
  PencilKit-Strokes wären dafür übersteigert. Wenn später Polygon-Masks
  oder Freihand-Skizzen dazu kommen, kann PencilKit nachgereicht werden.
- **Apple-Pencil-Support** trotzdem grundsätzlich da: SwiftUI's
  `DragGesture` reagiert auf Pencil-Eingaben genauso wie auf Finger.

## Verschoben auf β-3-Extension oder später

- **Anki-Import** (`.apkg`-Parser): Web parsed client-side und ruft
  `POST /cards` pro Karte. Native bräuchte eigenen Swift-Parser für
  Anki-Pakete (Plist/sqlite/.apkg) — eigener Brocken, nicht
  blockierend für andere Phasen.
- **Card-Edit** (PATCH /cards/:id): Card-Create reicht für Web-Parität
  in v1, Edit kann später nachgereicht werden.
- **Distractor-Vorschau** für Multiple-Choice-Editor: Server liefert
  Distractors zur Lernzeit (`/decks/:deckId/distractors`), Editor
  zeigt sie nicht — Web macht das auch nicht.

## Pflicht-Tests für β-2 (vor β-3-Start)

- [ ] Endurance-Test auf realem Gerät: 200+ Karten lernen, Flugmodus
  zwischendurch — alle Grades landen am Server nach Reconnect.
- [ ] Cross-Check mit Web: Karte gegrade in Native → Web zeigt
  identischen Review-State nach Reload.

## Cross-Refs

- `../mana/docs/playbooks/CARDS_NATIVE_GREENFIELD.md` — Greenfield-Plan SOT
- `../mana/docs/MANA_SWIFT.md` — Plattform-SOT
- `../cards/CLAUDE.md` — Cards-Repo
- `../cards/STATUS.md` — Web-Phasenstand (Referenz)
- `../mana-swift-core/CLAUDE.md` — ManaCore-Konventionen
- `CLAUDE.md` — Repo-Konventionen