refactor: Migration auf ManaWebShell + ManaTheme.paper aus mana-swift-* v1.6.0/v0.6.0

ManaWebShell aus mana-swift-ui v0.6.0 ersetzt den lokalen
`Sources/Features/WebShell/`-Ordner. WebShellCoordinator, WebShell-
View, WebShellScripts geloescht (~430 LOC). CookieBridge bleibt
lokal (App-spezifischer Cookie-SSO-Pfad fuer .mana.how), wandert
nach `Sources/Core/WebShell/CookieBridge.swift`.

`RootView.makeWebShellConfig()` baut Config mit Host-Whitelist
`zitare.com` + `www.zitare.com` + `*.mana.how`, ZitareTheme-Hints,
`syncDarkMode(localStorageKey: "zitare-mode")` und `hideElements`
fuer den zitare-web-Header.

ZitareTheme forwarded auf ManaTheme.paper aus mana-swift-core
v1.6.0 (~90 LOC weg, paper-Werte jetzt single-source in
`mana/packages/themes/src/variants/paper.css`).

AppConfig.userAgent als plattform-spezifischer Helper hinzu.

20/20 Unit-Tests gruen.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Till JS 2026-05-17 21:13:16 +02:00
parent e139a382d8
commit 4b00c4ecdf
8 changed files with 72 additions and 534 deletions

View file

@ -1,6 +1,41 @@
import ManaCore
import ManaWebShell
import SwiftUI
@MainActor
private func makeWebShellConfig() -> WebShellConfig {
WebShellConfig(
allowedHosts: [
"zitare.com",
"www.zitare.com",
"*.mana.how",
],
userAgent: AppConfig.userAgent,
backgroundColor: ZitareTheme.background,
progressTint: ZitareTheme.primary,
errorBackgroundColor: ZitareTheme.muted,
errorForegroundColor: ZitareTheme.foreground,
errorIconColor: ZitareTheme.warning,
userScripts: [
// Syncs System-Dark-Mode in den WebView; zitare-web liest
// `localStorage['zitare-mode']` beim First Paint und toggelt
// dann `.dark` auf <html>.
WebShellScripts.syncDarkMode(localStorageKey: "zitare-mode"),
// Versteckt den zitare-web-Header (Brand-Logo + Nav), weil
// die native TabBar bereits global navigiert.
WebShellScripts.hideElements(
selectors: [
"header[data-app-nav]",
"body header:has(a.brand)",
"body > header:first-of-type",
"body > div > header:first-of-type",
],
tagName: "hide-web-header"
),
]
)
}
/// Top-Level-View: TabView mit drei Tabs.
///
/// **Phase ζ-1:** Lesen + Erkunden laden `zitare.com` via `WebShellView`.
@ -16,13 +51,15 @@ struct RootView: View {
@State private var reloadCounter: Int = 0
@State private var healthStatus: HealthStatus = .unknown
private var webShellConfig: WebShellConfig { makeWebShellConfig() }
var body: some View {
TabView(selection: $selectedTab) {
WebShellView(target: readTarget)
WebShellView(target: readTarget, config: webShellConfig)
.tabItem { Label("Lesen", systemImage: "book") }
.tag(AppTab.read)
WebShellView(target: exploreTarget)
WebShellView(target: exploreTarget, config: webShellConfig)
.tabItem { Label("Erkunden", systemImage: "sparkle.magnifyingglass") }
.tag(AppTab.explore)

View file

@ -43,4 +43,12 @@ enum AppConfig {
/// zusätzlich rauskopieren. Bis dahin schlägt der Pull mit 404
/// fehl und `SnapshotSync.tryRefresh()` macht fail-soft no-op.
static let snapshotURL = webBaseURL.appendingPathComponent("index-min.json")
/// User-Agent-Suffix für WKWebView (ManaWebShell). WKWebView hängt
/// das an seinen Standard-UA an, ersetzt ihn nicht.
#if os(macOS)
static let userAgent = "ZitareNative/0.1 (macOS)"
#else
static let userAgent = "ZitareNative/0.1 (iOS)"
#endif
}

View file

@ -1,105 +1,28 @@
import ManaTokens
import SwiftUI
#if canImport(UIKit)
import UIKit
private typealias PlatformColorType = UIColor
#elseif canImport(AppKit)
import AppKit
private typealias PlatformColorType = NSColor
#endif
/// Paper-Variant aus `mana/packages/themes/src/variants/paper.css`.
/// Lokal in zitare-native nachgebaut, weil ManaTokens noch keine
/// Variants kennt.
/// Zitare-Theme forwarded auf ``ManaTheme/paper`` aus
/// `mana-swift-core` v1.6.0 (dieselbe Variant wie zitare-web).
///
/// Sepia, warm, lese-fokussiert skeumorph an Druckpapier angelehnt,
/// passt zum (read)-Surface der Web-App.
/// Bis v1.5.x lebte hier ein ~90-LOC-HSL-Apparat als lokaler Nachbau
/// der `paper.css`-Variant. Mit v1.6.0 liefert ManaTokens alle acht
/// Web-Theme-Variants nativ `paper` ist eine davon.
///
/// `ZitareTheme` bleibt als dünner Alias bestehen, damit bestehende
/// Call-Sites nicht in einem Sprint umziehen müssen. Neue Call-Sites
/// bevorzugen direkt `ManaTheme.paper.<token>` (oder
/// `@Environment(\.manaTheme)`).
enum ZitareTheme {
/// Page-Hintergrund (warmes Off-White / dunkles Sepia)
static let background = dynamic(light: HSL(38, 28, 95), dark: HSL(24, 14, 9))
/// Standard-Text
static let foreground = dynamic(light: HSL(20, 14, 16), dark: HSL(38, 24, 88))
/// Card, Panel, Modal
static let surface = dynamic(light: HSL(0, 0, 100), dark: HSL(24, 12, 13))
/// Hover-State auf Surface
static let surfaceHover = dynamic(light: HSL(38, 24, 92), dark: HSL(24, 14, 17))
/// Disabled-Felder, Skeleton
static let muted = dynamic(light: HSL(38, 20, 90), dark: HSL(24, 12, 18))
/// Sekundär-Text, Placeholder
static let mutedForeground = dynamic(light: HSL(20, 14, 50), dark: HSL(38, 12, 60))
/// Rahmen, Trennlinien
static let border = dynamic(light: HSL(38, 18, 80), dark: HSL(24, 10, 25))
/// Zitare-Primary warmes Terra/Sienna im Light, weicheres Sienna im Dark
static let primary = dynamic(light: HSL(18, 50, 38), dark: HSL(24, 60, 65))
/// Text auf Primary
static let primaryForeground = dynamic(light: HSL(0, 0, 100), dark: HSL(24, 14, 9))
static let error = dynamic(light: HSL(0, 65, 45), dark: HSL(0, 60, 55))
static let success = dynamic(light: HSL(135, 35, 35), dark: HSL(135, 35, 55))
static let warning = dynamic(light: HSL(38, 80, 40), dark: HSL(38, 70, 55))
// MARK: - HSL Helper
struct HSL {
let hue: Double
let saturation: Double
let lightness: Double
init(_ hue: Double, _ saturation: Double, _ lightness: Double) {
self.hue = hue
self.saturation = saturation
self.lightness = lightness
}
var color: Color {
Color(
hue: hue / 360.0,
saturation: saturation / 100.0,
brightness: brightnessFromLightness(),
opacity: 1.0
)
}
/// HSL HSB Konversion (SwiftUI Color nutzt HSB).
private func brightnessFromLightness() -> Double {
let l = lightness / 100.0
let s = saturation / 100.0
return l + s * min(l, 1 - l)
}
}
private static func dynamic(light: HSL, dark: HSL) -> Color {
#if canImport(UIKit)
return Color(
PlatformColorType { trait in
trait.userInterfaceStyle == .dark
? PlatformColorType(dark.color)
: PlatformColorType(light.color)
}
)
#elseif canImport(AppKit)
return Color(
PlatformColorType(name: nil) { appearance in
let isDark = appearance.bestMatch(
from: [.darkAqua, .aqua]
) == .darkAqua
return isDark
? PlatformColorType(dark.color)
: PlatformColorType(light.color)
}
)
#else
return light.color
#endif
}
static let background = ManaTheme.paper.background
static let foreground = ManaTheme.paper.foreground
static let surface = ManaTheme.paper.surface
static let surfaceHover = ManaTheme.paper.surfaceHover
static let muted = ManaTheme.paper.muted
static let mutedForeground = ManaTheme.paper.mutedForeground
static let border = ManaTheme.paper.border
static let primary = ManaTheme.paper.primary
static let primaryForeground = ManaTheme.paper.primaryForeground
static let error = ManaTheme.paper.error
static let success = ManaTheme.paper.success
static let warning = ManaTheme.paper.warning
}

View file

@ -1,155 +0,0 @@
import Foundation
import SwiftUI
import WebKit
#if canImport(UIKit)
import UIKit
#endif
/// `WKNavigationDelegate` + `WKUIDelegate` für `WebShellView`. Hält den
/// reactive `WebNavState` aktuell, lenkt externe Links in den System-
/// Browser und treibt Pull-to-Refresh an.
///
/// Nicht `Sendable`: Lebt auf `MainActor` (Closures von WKWebView
/// liefern auf Main). KVO-Observations werden bei `deinit` entfernt.
@MainActor
final class WebShellCoordinator: NSObject, WKNavigationDelegate, WKUIDelegate {
let navState: WebNavState
let openURL: OpenURLAction
var lastTarget: WebTarget?
private var progressObservation: NSKeyValueObservation?
private var loadingObservation: NSKeyValueObservation?
private var canGoBackObservation: NSKeyValueObservation?
private var urlObservation: NSKeyValueObservation?
#if canImport(UIKit)
private weak var refreshControl: UIRefreshControl?
#endif
init(navState: WebNavState, openURL: OpenURLAction) {
self.navState = navState
self.openURL = openURL
super.init()
}
deinit {
progressObservation?.invalidate()
loadingObservation?.invalidate()
canGoBackObservation?.invalidate()
urlObservation?.invalidate()
}
func observe(webView: WKWebView) {
progressObservation = webView.observe(\.estimatedProgress, options: [.new]) { [weak self] _, change in
guard let value = change.newValue else { return }
Task { @MainActor in
self?.navState.estimatedProgress = value
}
}
loadingObservation = webView.observe(\.isLoading, options: [.new]) { [weak self] _, change in
guard let value = change.newValue else { return }
Task { @MainActor in
self?.navState.isLoading = value
}
}
canGoBackObservation = webView.observe(\.canGoBack, options: [.new]) { [weak self] _, change in
guard let value = change.newValue else { return }
Task { @MainActor in
self?.navState.canGoBack = value
}
}
urlObservation = webView.observe(\.url, options: [.new]) { [weak self] _, change in
let value = change.newValue ?? nil
Task { @MainActor in
self?.navState.currentURL = value
}
}
}
func load(_ url: URL, into webView: WKWebView) {
Log.web.info("WebShell load: \(url.absoluteString, privacy: .public)")
navState.lastError = nil
let request = URLRequest(url: url)
webView.load(request)
}
#if canImport(UIKit)
func attachRefresh(_ control: UIRefreshControl, webView: WKWebView) {
refreshControl = control
control.addAction(
UIAction { [weak self, weak webView] _ in
webView?.reload()
Task { @MainActor in
self?.refreshControl?.endRefreshing()
}
},
for: .valueChanged
)
}
#endif
// MARK: - WKNavigationDelegate
func webView(
_: WKWebView,
decidePolicyFor navigationAction: WKNavigationAction
) async -> WKNavigationActionPolicy {
guard let url = navigationAction.request.url else { return .allow }
// Eigene Host-Whitelist: alles auf zitare.com bzw. .mana.how darf
// im WebView öffnen. Alles andere geht in den System-Browser.
// Custom-Scheme zitare:// catchen wir hier nicht Universal-
// Links auf zitare.com sind der präferierte Pfad.
if let host = url.host, isAllowedHost(host) {
return .allow
}
if url.scheme == "http" || url.scheme == "https" {
Log.web.info("WebShell → openURL extern: \(url.absoluteString, privacy: .public)")
openURL(url)
return .cancel
}
return .cancel
}
func webView(_: WKWebView, didFail _: WKNavigation, withError error: Error) {
Log.web.warning("didFail: \(String(describing: error), privacy: .public)")
navState.lastError = (error as NSError).localizedDescription
}
func webView(_: WKWebView, didFailProvisionalNavigation _: WKNavigation, withError error: Error) {
Log.web.warning("didFailProvisional: \(String(describing: error), privacy: .public)")
navState.lastError = (error as NSError).localizedDescription
}
func webView(_: WKWebView, didFinish _: WKNavigation) {
navState.lastError = nil
}
// MARK: - WKUIDelegate
func webView(
_ webView: WKWebView,
createWebViewWith _: WKWebViewConfiguration,
for navigationAction: WKNavigationAction,
windowFeatures _: WKWindowFeatures
) -> WKWebView? {
// `target=_blank`-Links: kein neues Fenster aufmachen, sondern
// im aktuellen WebView laden bzw. extern öffnen.
if let url = navigationAction.request.url {
if let host = url.host, isAllowedHost(host) {
webView.load(navigationAction.request)
} else {
openURL(url)
}
}
return nil
}
// MARK: - Helpers
private func isAllowedHost(_ host: String) -> Bool {
host == "zitare.com"
|| host == "www.zitare.com"
|| host.hasSuffix(".mana.how")
|| host == "mana.how"
}
}

View file

@ -1,90 +0,0 @@
import Foundation
import WebKit
/// User-Scripts, die in jeden `WKWebView` injiziert werden.
///
/// `WKUserScript` ist MainActor-isolated; deshalb sind die Factory-
/// Methoden hier ebenfalls MainActor. Aufrufer leben sowieso auf Main
/// (SwiftUI `makeUIView`/`makeNSView` sind MainActor).
@MainActor
enum WebShellScripts {
/// Versteckt den zitare-Web-Header (`<header>` mit `<a class="brand">`),
/// weil die native TabBar bereits global navigiert. Footer und
/// Hauptinhalt bleiben sichtbar.
///
/// CSS wird at document.start als `<style>`-Tag injiziert vor dem
/// First Paint, kein Flicker.
/// Synct den System-Dark-Mode in den WebView. Zitare-Web liest
/// `localStorage['zitare-mode']` beim First Paint (Inline-Script
/// in `app.html`) und togglet eine `.dark`-Klasse auf `<html>`.
///
/// In der nativen App wurde der Theme-Toggle-Button im Web-Header
/// ausgeblendet (`hideWebHeader`), deshalb kann der User
/// localStorage nicht selber setzen. Statt-dessen lauschen wir auf
/// `prefers-color-scheme` und schreiben das passende Value vor
/// jeder Page-Load und bei jedem System-Switch.
///
/// Greift sowohl bei Cold-Load (atDocumentStart, vor app.html-
/// Inline-Script) als auch bei nachträglichem System-Wechsel
/// (`matchMedia`-Listener auf der selben Page).
static let syncDarkMode: WKUserScript = .init(
source: """
(function() {
function apply(isDark) {
try {
if (isDark) localStorage.setItem('zitare-mode', 'dark');
else localStorage.removeItem('zitare-mode');
} catch (e) {}
var html = document.documentElement;
if (!html) return;
if (isDark) html.classList.add('dark');
else html.classList.remove('dark');
}
var mq = window.matchMedia('(prefers-color-scheme: dark)');
apply(mq.matches);
// Listener für Live-Switch während die Page offen ist.
if (mq.addEventListener) {
mq.addEventListener('change', function(e) { apply(e.matches); });
}
})();
""",
injectionTime: .atDocumentStart,
forMainFrameOnly: true
)
/// Mehrere Selektor-Strategien stapeln, damit ein Klassen-Rename
/// oder Markup-Refactor in zitare-web das Hide nicht still bricht:
///
/// 1. `header[data-app-nav]` explizit gesetztes Attribut, falls
/// zitare-web es irgendwann markieren will (heute nicht da).
/// 2. `body header:has(a.brand)` strukturell: ein `<header>`,
/// der einen `a.brand`-Link enthält. Matched die heutige
/// SvelteKit-Komponente (Brand Zitare" links oben).
/// 3. `body > * > header:first-of-type` positionell: erster
/// `<header>` direkt unter dem Top-Level-Wrapper. Greift wenn
/// `a.brand` mal verschwindet.
///
/// `body > * > header:first-of-type` ist absichtlich konservativ
/// (matcht nur einen `<header>` pro `<body>`-Direktkind), damit
/// nicht ungewollt nested Article-Header gehidet werden.
static let hideWebHeader: WKUserScript = .init(
source: """
(function() {
var css = [
'header[data-app-nav],',
'body header:has(a.brand),',
'body > header:first-of-type,',
'body > div > header:first-of-type {',
' display: none !important;',
'}'
].join('\\n');
var style = document.createElement('style');
style.setAttribute('data-zitare-native', 'hide-web-header');
style.textContent = css;
(document.head || document.documentElement).appendChild(style);
})();
""",
injectionTime: .atDocumentStart,
forMainFrameOnly: true
)
}

View file

@ -1,187 +0,0 @@
import SwiftUI
import WebKit
/// Phase ζ-1: SwiftUI-Hülle um `WKWebView`. Eine `WebShellView`-Instanz
/// gehört zu einem Tab und behält ihren Web-State (Scroll-Position,
/// Browser-History) während der Tab aktiv bleibt.
///
/// **Verhalten:**
/// - Lädt `target` beim ersten Auftauchen.
/// - Wechselt `target` während die View lebt lädt neue URL.
/// - Pull-to-Refresh über `UIRefreshControl` (iOS).
/// - External-Links (anderer Host, `target=_blank`) öffnen im System-
/// Browser via `openURL`-Environment, nicht im WebView.
/// - Cookies werden über das default `WKWebsiteDataStore` geteilt,
/// sodass `CookieBridge` einmal injizierte `mana.access`-Cookies
/// sichtbar sind.
struct WebShellView: View {
let target: WebTarget
@State private var navState = WebNavState()
@Environment(\.openURL) private var openURL
var body: some View {
VStack(spacing: 0) {
if navState.isLoading {
ProgressView(value: navState.estimatedProgress)
.progressViewStyle(.linear)
.frame(height: 2)
}
#if canImport(UIKit)
WebViewRepresentable(
target: target,
navState: navState,
openURL: openURL
)
.frame(maxWidth: .infinity, maxHeight: .infinity)
.background(ZitareTheme.background)
#elseif canImport(AppKit)
MacWebViewRepresentable(
target: target,
navState: navState,
openURL: openURL
)
.frame(maxWidth: .infinity, maxHeight: .infinity)
.background(ZitareTheme.background)
#endif
if let error = navState.lastError {
errorBar(error)
}
}
.frame(maxWidth: .infinity, maxHeight: .infinity)
}
private func errorBar(_ message: String) -> some View {
HStack(spacing: 12) {
Image(systemName: "exclamationmark.triangle.fill")
.foregroundStyle(ZitareTheme.warning)
Text(message)
.font(.caption)
.lineLimit(2)
Spacer()
}
.padding(.horizontal, 12)
.padding(.vertical, 8)
.background(ZitareTheme.muted)
}
}
/// URL + monoton wachsende `reloadToken`. Ein neuer Token zwingt den
/// WebView, dieselbe URL nochmal zu laden wird gebraucht wenn der
/// User auf einen Universal-Link tappt, der zur aktuellen URL führt.
struct WebTarget: Equatable {
let url: URL
let reloadToken: Int
init(url: URL, reloadToken: Int = 0) {
self.url = url
self.reloadToken = reloadToken
}
}
/// Reactive Navigation-State, geteilt zwischen SwiftUI und Coordinator.
@Observable
final class WebNavState {
var isLoading: Bool = false
var estimatedProgress: Double = 0
var lastError: String?
var currentURL: URL?
var canGoBack: Bool = false
}
#if canImport(UIKit)
import UIKit
private struct WebViewRepresentable: UIViewRepresentable {
let target: WebTarget
let navState: WebNavState
let openURL: OpenURLAction
func makeCoordinator() -> WebShellCoordinator {
WebShellCoordinator(navState: navState, openURL: openURL)
}
func makeUIView(context: Context) -> WKWebView {
let config = WKWebViewConfiguration()
config.websiteDataStore = .default()
config.applicationNameForUserAgent = "ZitareNative/0.1 (iOS)"
// Reihenfolge: erst Theme syncen, dann Header verstecken.
config.userContentController.addUserScript(WebShellScripts.syncDarkMode)
config.userContentController.addUserScript(WebShellScripts.hideWebHeader)
let webView = WKWebView(frame: .zero, configuration: config)
webView.navigationDelegate = context.coordinator
webView.uiDelegate = context.coordinator
webView.allowsBackForwardNavigationGestures = true
// Ohne diese drei flackert WKWebView bis zum first paint weiß
// gegen das Paper-Theme egal was die SwiftUI-Hülle als
// Background setzt.
webView.isOpaque = false
webView.backgroundColor = .clear
webView.scrollView.backgroundColor = .clear
webView.scrollView.refreshControl = makeRefreshControl(
webView: webView,
coordinator: context.coordinator
)
context.coordinator.observe(webView: webView)
context.coordinator.load(target.url, into: webView)
return webView
}
func updateUIView(_ webView: WKWebView, context: Context) {
let coord = context.coordinator
if coord.lastTarget != target {
coord.load(target.url, into: webView)
coord.lastTarget = target
}
}
private func makeRefreshControl(
webView: WKWebView,
coordinator: WebShellCoordinator
) -> UIRefreshControl {
let refresh = UIRefreshControl()
coordinator.attachRefresh(refresh, webView: webView)
return refresh
}
}
#elseif canImport(AppKit)
import AppKit
private struct MacWebViewRepresentable: NSViewRepresentable {
let target: WebTarget
let navState: WebNavState
let openURL: OpenURLAction
func makeCoordinator() -> WebShellCoordinator {
WebShellCoordinator(navState: navState, openURL: openURL)
}
func makeNSView(context: Context) -> WKWebView {
let config = WKWebViewConfiguration()
config.websiteDataStore = .default()
config.applicationNameForUserAgent = "ZitareNative/0.1 (macOS)"
// Reihenfolge: erst Theme syncen, dann Header verstecken.
config.userContentController.addUserScript(WebShellScripts.syncDarkMode)
config.userContentController.addUserScript(WebShellScripts.hideWebHeader)
let webView = WKWebView(frame: .zero, configuration: config)
webView.navigationDelegate = context.coordinator
webView.uiDelegate = context.coordinator
webView.allowsBackForwardNavigationGestures = true
// macOS-Pendant zu UIView.isOpaque=false sonst weißer
// Flash vor first paint.
webView.setValue(false, forKey: "drawsBackground")
context.coordinator.observe(webView: webView)
context.coordinator.load(target.url, into: webView)
return webView
}
func updateNSView(_ webView: WKWebView, context: Context) {
let coord = context.coordinator
if coord.lastTarget != target {
coord.load(target.url, into: webView)
coord.lastTarget = target
}
}
}
#endif

View file

@ -42,6 +42,8 @@ targets:
product: ManaTokens
- package: ManaSwiftUI
product: ManaAuthUI
- package: ManaSwiftUI
product: ManaWebShell
- target: ZitareWidgetExtension
embed: true
- target: ZitareShareExtension