zitare-native/docs/NATIVE_LIFT_PLAN.md

Native-Lift Plan — zitare-native (ζ → η)

Stand: 2026-05-22 — Planung. Drei Antworten von Till liegen vor (Offline-first + lokal-first-Suche + SafariView für Legal). Dieser Plan ersetzt die Hybrid-Strategie aus dem Greenfield-Playbook ../../mana/docs/playbooks/ZITARE_NATIVE_GREENFIELD.md für die Read-Surfaces. Submit / ShareExt / Widget / Spotlight bleiben in ihrer schon-nativen Form.

SOT für die Status-Spur: dieses File + PLAN.md. Die ζ-Phasen sind historisch (ζ-0/ζ-1/ζ-2 erledigt), die η-Phasen sind der Lift.

Was sich ändert vs. Hybrid

Bereich	Vorher (ζ)	Nachher (η)
Lesen-Tab	WebShellView auf zitare.com	QuoteFeedView (SwiftUI), Daten aus SwiftData
Erkunden-Tab	WebShellView auf zitare.com/explore	ExploreView (SwiftUI) mit Facet-Filter
Quote-Detail	Web-Route /q/<slug>	QuoteDetailView (nativ), Deep-Link-Target
Author/Source/Thema	Web-Route	Native Detail-Views
Search	Pagefind im Web	SwiftData-FTS lokal + API-Fallback
Account	(heute schon Stub)	AccountView voll nativ, ManaAuthUI
Impressum/Datenschutz/Lizenz	Web-Routen	SFSafariViewController-Sheet auf zitare.com/<page>
ManaWebShell-Dep	benutzt	wird komplett entfernt
CookieBridge.swift	benötigt	entfällt (kein WebView, kein Cookie-SSO mehr)
Cookie-SSO mana.access → WebView	Phase 2.G	gestrichen
AASA applinks	zitare.com + app.zitare.com	bleibt; Routen jetzt nativ
Snapshot index-min.json	nur Meta (11 Quotes, Slugs+Tags)	erweitert auf Volltext + Author-/Source-/Themen-Stammdaten
Datenmodell	nur SnapshotQuote (Stub)	volles SwiftData-Schema gespiegelt zu zitare-DB

Architektonische Invarianten (η)

Diese ersetzen die alten Hybrid-Invarianten in CLAUDE.md:

1. Pure SwiftUI für alle Surfaces. Kein WKWebView mehr im App- Binary. ManaWebShell-Dep raus aus project.yml.
2. Offline-first Lesen. SwiftData ist Primary-Store, API ist Fallback bei Cache-Miss + Sync-Quelle. Flugmodus-Test ist Akzeptanz- Kriterium für η-2.
3. Quote-Korpus ist Snapshot. Beim Launch + Background-Refresh wird index-full.json gepullt, ETag-aware, in SwiftData persistiert, per App-Group an Widget + ShareExt + Spotlight durchgereicht.
4. Server gewinnt bei Schema-Konflikt. SwiftData-Modelle sind eine abgeleitete Spiegelung des Drizzle-Schemas in zitare/apps/api/. Bei Drift: Server-Schema, dann Snapshot-Format, dann Native-Modell.
5. Search lokal-first. Lokale FTS aus SwiftData; bei < 3 Treffern oder leerem Result Server-Fallback (GET /api/v1/quotes?q=).
6. Legal-Seiten via SafariView. Impressum / Datenschutz / Lizenz öffnen SFSafariViewController. Das ist die einzige zugelassene Browser-Brücke und nur für statisches Verein-Recht-Material.
7. Schreiben bleibt Submit-only in v1. Edit / Moderation / Flags- Verwaltung kommen NICHT in die App. Bleiben Web (app.zitare.com). Wer das braucht, öffnet Safari.
8. Universal-Links auf zitare.com lösen ins native Surface. AASA bleibt, aber onContinueUserActivity routet auf SwiftUI-Views, nicht in einen WebView-Tab.
9. Keine Web-Re-Implementation von Web-Funktion. Wenn eine Read- Ansicht in der App fehlt, die im Web existiert: erst Web im SOT prüfen, dann nativ nachziehen. Kein einseitiger Native-Vorlauf, der das Web abhängt.

Phasen-Plan

Erfolgskriterium ist je eine Sache. Nicht in die nächste Phase arbeiten, bevor die vorherige geschlossen ist.

η-0 — De-Hybrid (Vorbereitung)

• CLAUDE.md Invarianten 1, 2, 8 ersetzen durch die η-Liste oben.
• ManaWebShell-Dep aus project.yml entfernen.
• Sources/Core/WebShell/CookieBridge.swift löschen.
• RootView.swift auf vier native Tabs umstellen (Lesen / Erkunden / Einreichen / Konto) — Lesen + Erkunden zeigen erstmal Platzhalter („wird in η-2/η-4 implementiert").
• Features/Settings/SettingsView.swift + Features/Account/AccountView.swift von WebView-Verweisen befreien (Settings-„Hilfe → öffne Browser" bleibt, aber als SafariView).
• Submit / ShareExt / Widget bleiben unangetastet.

Erfolg: Build grün auf iOS-Simulator, kein WKWebView-Symbol im Binary (nm | grep WKWebView leer), App startet, alle vier Tabs sichtbar, Lesen + Erkunden zeigen Platzhalter-View.

η-1 — Snapshot v2 + SwiftData-Schema

Cross-Repo: zitare-web muss liefern, bevor η-2 startet.

Web-Repo-Aufgaben (../zitare/apps/zitare/):

• Build-Script erweitern: index-full.json mit allen Quote-Feldern inkl. text, language, lengthBucket, form, createdAt, author, source, tags[], themes[], plus Author-/Source-/Theme-/Place-/ Epoch-/Role-Stammdaten als eigene Collections (authors.json, sources.json, themes.json, places.json, epochs.json, roles.json).
• ETag-Header für jeden dieser Endpoints (Cache-Control: 1h).
• Stabile URL: https://zitare.com/index-full.json (Apex), nicht über mana.how.
• Größen-Budget: Korpus < 5 MB unkomprimiert für die nächsten ~5000 Quotes (Pagination dann in η-5 nachgedacht, heute 11 Quotes).

Native-Aufgaben:

• SwiftData-Modelle in Sources/Core/Snapshot/Models/: SDQuote, SDAuthor, SDSource, SDTheme, SDPlace, SDEpoch, SDRole, SDTag. Relations 1:1 mit Drizzle.
• SnapshotSync.swift: lädt parallel die sieben Collections, diffed gegen lokalen Store, persistiert atomar.
• App-Group-Container statt nur-App-Container, damit Widget + ShareExt + Spotlight denselben Store lesen.
• ETag im UserDefaults persistieren, If-None-Match schicken.

Erfolg: Nach Cold-Start lädt App den vollen Korpus, SwiftData- Store hat erwartete Row-Counts, ETag spart Bytes beim Reload.

η-2 — Read-Core nativ (Heute, Quote-Detail, Author-Detail)

• QuoteCard-Komponente (Text, Author, Theme-Chips, lengthBucket).
• HeuteView: deterministisches Tages-Quote (Hash über Datum + Korpus- Count). Match-Logik mit Widget abgleichen.
• QuoteDetailView für Deep-Link /q/<slug>: Vollansicht, Author- Link, Source-Link, Theme-Chips, Quelle-Metadaten, Lizenz-Hinweis.
• AuthorDetailView für /a/<slug>: Bio (Name, Native-Name, Places, Epochs, Roles), Quote-Liste des Authors.
• DeepLinkRouter umverdrahten: keine WebShell-Targets mehr, sondern NavigationPath-Push.

Erfolg: Flugmodus, frische Install, App zeigt Heute-Quote + Quote-Detail nach Universal-Link aus Mail-App.

η-3 — Read-Browse (Source, Theme, Place, Role, Epoch, Language)

• Detail-Views je Entity mit Listing der zugehörigen Quotes.
• SourceDetailView für /c/<slug>.
• ThemeListView, ThemeDetailView für /thema/<slug>.
• PlaceListView (Regionen) für /region/<slug>.
• Analog Roles / Epochs / Languages.
• Konsistente EntityListSection-Komponente (Title, Count, Chip-Grid).

Erfolg: Alle Web-Deep-Link-Pattern aus app-manifest.json rufen die richtige native View auf.

η-4 — Explore + Filter

• ExploreView als kombinierte Filter-Oberfläche: Sprache, Length-Bucket, Form, Theme, Region, Epoche, Role.
• Filter-State als @Observable-Klasse, persistierbar in UserDefaults.
• Live-Result-Counter über SwiftData-@Query mit dynamischem Predicate.
• iPad: NavigationSplitView mit Filter-Sidebar + Result-List.

Erfolg: Filter „Roman + DE + lang" zeigt korrekte Subset live, ohne Server-Call.

η-5 — Search (lokal + Server-Fallback)

• Lokale FTS:
  • Bei Snapshot-Import: pro Quote normalizedText (lowercase, diakritika-frei) ableiten, in SDQuote.searchTokens als [String] (oder als String mit Space-Separator) speichern.
  • Query-Splitting: Whitespace + Diakritika-Normalisierung.
  • SwiftData-Predicate mit contains über searchTokens.
• Server-Fallback:
  • Wenn lokaler Result-Count < 3 ODER Query-Länge < 3 Token: parallel GET /api/v1/quotes?q=<query> (Endpoint muss in zitare-api vorhanden sein — prüfen, ggf. ergänzen).
  • Server-Results mit Marker „Online-Treffer" einsortieren, nicht persistieren.
• UI: SearchView mit searchable(), Result-List mit Source-Marker (lokal vs. online), Empty-State.

Erfolg: Begriff der existiert lokal kommt offline; seltener Begriff bringt Online-Treffer dazu, der vom Sync nicht abgedeckt war.

η-6 — Account nativ (vollständige Auth-Surface)

• AccountView heute hat Health-Status + Sign-In-Button als Stub.
• Voll bauen: Profil-Info, Gerätesitzungen, Sign-Out-Button, Link auf Web-Konto-Verwaltung via SafariView.
• Eigene Submissions-Liste (GET /api/v1/me/submissions, falls vorhanden — sonst Cross-Repo-Aufgabe).
• Keine WebView-Verlinkung mehr.

Erfolg: Sign-In + Sign-Out vollständig nativ, JWT im Keychain verifizierbar.

η-7 — Legal via SafariView

• LegalSheet.swift: UIViewControllerRepresentable um SFSafariViewController (iOS) / NSWorkspace.open (macOS).
• Drei Links im Settings-Tab: Impressum, Datenschutz, Lizenz.
• macOS: öffnet System-Browser, kein SafariView dort.

Erfolg: Tap auf „Impressum" öffnet https://zitare.com/impressum im SFSafariViewController-Sheet, nicht im App-WebView (gibt's nicht mehr).

η-8 — Submit + ShareExt + Spotlight an Snapshot v2 anpassen

• Submit-Author-Autocomplete: heute über ZitareAPI.searchAuthors (live API). Jetzt erstmal lokal aus Snapshot (instant), bei < 3 Treffern Server-Fallback.
• ShareExt: sollte schon nativ sein, prüfen ob es WebShell-Imports hat (grep WebShell ShareExtension/).
• Spotlight: jetzt mit Volltext indexieren statt nur Meta — searchableItem.contentDescription = quote.text.prefix(200).

Erfolg: Spotlight findet Quote nach Volltext-Fragment, nicht nur nach Author/Theme.

η-9 — Polish (iPad-Split, Accessibility, macOS-Layout)

• iPad: NavigationSplitView für Quote-Listen.
• macOS: Window-Layout, Sidebar-NavSplit statt TabBar.
• Dynamic Type, VoiceOver-Labels für QuoteCard, Theme-Sync mit System-Dark-Mode (ohne JS-Bridge, weil ohne WebView).
• Haptics für Heute-Quote-Refresh.

Erfolg: Eine Woche Solo-Nutzung ohne offene Browser-Tabs zu Zitare-Inhalten.

η-10 — TestFlight

• App-Store-Connect: Build hochladen, Review-Notes, Screenshots.
• Apple-Dev-Portal-Blocker (App-Group) ist hier vermutlich längst erledigt; falls nicht: nachziehen vor Upload.

Erfolg: TestFlight-Tester können Korpus lesen + Quote einreichen.

Cross-Repo-Aufgaben

../zitare/apps/zitare/ (Web-Build)

• index-full.json Build-Script + Endpoint (η-1 Blocker)
• Stammdaten-Collections: authors.json, sources.json, themes.json, places.json, epochs.json, roles.json, languages.json (η-1 Blocker)
• ETag-Header auf allen Snapshot-Endpoints
• AASA bleibt wie heute (kein Change)

../zitare/apps/api/ (API)

• GET /api/v1/quotes?q=... Volltext-Search prüfen — wenn nicht vorhanden, ergänzen (Drizzle + PG to_tsvector oder einfaches ilike für Anfang). Search-Quality-Diskussion in η-5.
• GET /api/v1/me/submissions für AccountView prüfen, ggf. ergänzen (η-6).
• Wire-Format-Check: Native-Codable-Structs gegen Hono-zod- Response in η-2/η-3 abgleichen, Test-Fixtures aus echten Server-Responses einchecken.

../mana/docs/playbooks/ZITARE_NATIVE_GREENFIELD.md

• Status-Banner ergänzen: Read-Surface-Strategie revidiert 2026-05-22, jetzt fully-native; SOT für laufende Arbeit ist dieses File.

Apple Developer Portal

• App-Group group.ev.mana.zitare registrieren — falls noch offen aus ζ-0/ζ-2. Selbe Blocker-Lage wie cards/memoro/moodlit.

Offene Punkte

• Snapshot-Größe-Skalierung. Heute 11 Quotes, Plan ist < 5 MB unkomprimiert. Ab welcher Korpus-Größe kippt das? Wahrscheinlich

  5000 Quotes. Antwort: Pagination + Sync-Deltas in η-5+. Heute irrelevant.

• Multilingual FTS. Lokale Search splittet nach Whitespace, ist diakritika-frei. Stemming (dt + en + andere) ist nicht im Plan. Falls Such-Qualität schwach: in η-5 nachschärfen oder als „kennen wir, später" akzeptieren.
• Quote-Text-Formatierung. Hat ein Quote-Text Markdown-artige Zeichen (Zeilen­umbrüche, Hervorhebung)? Falls ja: in η-2 mit AttributedString rendern. Web-SOT prüfen.
• macOS-Layout. Bisher steht macOS auf Apple-Dev-Portal-Blocker. Sobald entblockt: SplitView statt TabBar. In η-9.
• Submit-Pfad und Online-Pflicht. Submit braucht Auth + API. Wenn offline: queue + retry — ist heute schon so vorgesehen, prüfen, ob die Queue noch passt nach SwiftData-Schema-Lift.
• Schema-Versions-Tag im Snapshot. SwiftData-Migrationen für künftige Schema-Änderungen brauchen einen Versions-Marker. In η-1 mit eingeplant (SchemaV1.swift), aber Migrations-Strategie ist „lokal löschen + neu sync" für v0.x → v1.0.
• Was passiert mit /feed.rss? Deep-Link-Pattern existiert. Native-Antwort: SafariView oder „nicht in App"-Toast? In η-2 entscheiden.
• app.zitare.com Universal-Link. Heute AASA-Ziel. Wenn die SPA dort wegfällt für native Nutzer, brauchen wir AASA dort weiterhin (für Web-Fallback ja, für native Routing — als identisch zu zitare.com behandeln)? In η-2 routen wir beide Domains gleich, AASA bleibt redundant gepflegt.
• Web-App auf app.zitare.com selbst. Wenn native der primäre Read-Pfad wird, wozu existiert die SPA dann noch? Antwort: Browser-Nutzer + nicht-iOS/macOS-User + Moderation/Admin. Aber Frage rechtfertigt sich, ob die SPA aktiv weiterentwickelt wird oder einfriert. Nicht hier entscheiden, aber in zitare/STATUS.md diskutieren.

Was außerhalb bleibt

• Push-Pipeline. Widget reicht.
• Eigener Pagefind-Klon. Lokale FTS ist SwiftData-Predicate, nicht Web-Pagefind portiert.
• FSRS oder Lernen. Nicht Zitare-Scope.
• Crash-Reporting-SaaS. OSLog only (Compliance).
• Admin / Moderation / Edit in der App. Bleiben Web.