Phase 2 (Teil 1): Widget-Raster, Layout-Engine, Persistenz

Layout-Engine mit vier Spalten, testgetrieben. Widgets werden nicht stur
hintereinander gesetzt, sondern jeweils an die erste Stelle, an die sie passen.
Der Unterschied zeigt sich neben einem 2x2-Widget: dort bleiben rechts zwei
1x1-Plätze frei, die ein reines Anhängen dauerhaft leer ließe.

Persistenz unterscheidet zwei Fälle, die gleich aussehen und es nicht sind. Eine
leere Layout-Datei ist eine Aussage — der Nutzer hat alle Widgets entfernt. Eine
Datei, aus der nach dem Filtern unbekannter Kennungen nichts übrig bleibt, ist
dagegen ein Zeichen, dass sich die Kennungen geändert haben; dort wäre ein leeres
Panel eine stille Fehlfunktion, also greift das Standardlayout.

Beschädigte und fehlende Dateien führen beide zum Standardlayout statt zu einem
Absturz oder einem leeren Panel.

Die Panelgröße folgt dem Layout statt umgekehrt. Positioniert wird über
LayoutEngine.frame, nicht über LazyVGrid — das kann keine Kacheln über zwei
Zeilen führen, und genau das braucht der Mini-Monat.

Platzhalter-Widgets für alle 13 geplanten Karten. Sie tragen die endgültigen
Kennungen, damit gespeicherte Layouts weitergelten, wenn die echten Widgets sie
Phase für Phase ersetzen.

66 Tests grün.

Packages/OnyxKit/Sources/OnyxWidgetKit/LayoutEngine.swift

@@ -0,0 +1,154 @@
+import Foundation
+import CoreGraphics
+import OnyxDesign
+
+/// Die Größen, in denen ein Widget im Panel auftreten darf.
+public enum WidgetSize: String, Codable, Sendable, CaseIterable, Identifiable {
+    /// 1 × 1 — ein Messwert, ein Ring.
+    case small
+    /// 2 × 1 — Messwert mit Verlauf, kurze Liste.
+    case medium
+    /// 2 × 2 — Mini-Monat, Sensorliste.
+    case large
+    /// 4 × 1 — Medienzeile über die volle Breite.
+    case wide
+
+    public var id: String { rawValue }
+
+    public var columnSpan: Int {
+        switch self {
+        case .small: 1
+        case .medium, .large: 2
+        case .wide: 4
+        }
+    }
+
+    public var rowSpan: Int {
+        switch self {
+        case .small, .medium, .wide: 1
+        case .large: 2
+        }
+    }
+}
+
+/// Ein Widget an seinem Platz im Layout, wie der Nutzer es angeordnet hat.
+public struct WidgetPlacement: Codable, Equatable, Identifiable, Sendable {
+    public let id: UUID
+    public var widgetID: String
+    public var size: WidgetSize
+
+    public init(id: UUID = UUID(), widgetID: String, size: WidgetSize) {
+        self.id = id
+        self.widgetID = widgetID
+        self.size = size
+    }
+}
+
+public struct GridCell: Hashable, Sendable, CustomStringConvertible {
+    public let row: Int
+    public let column: Int
+
+    public init(row: Int, column: Int) {
+        self.row = row
+        self.column = column
+    }
+
+    public var description: String { "(\(row),\(column))" }
+}
+
+/// Ein Widget mit ausgerechneter Rasterposition.
+public struct ResolvedPlacement: Equatable, Identifiable, Sendable {
+    public let placement: WidgetPlacement
+    public let row: Int
+    public let column: Int
+
+    public var id: UUID { placement.id }
+    public var columnSpan: Int { placement.size.columnSpan }
+    public var rowSpan: Int { placement.size.rowSpan }
+}
+
+/// Setzt Widgets in ein Raster mit fester Spaltenzahl.
+public enum LayoutEngine {
+
+    public static let columns = 4
+    /// Kantenlänge eines 1×1-Feldes.
+    public static let cellSize: CGFloat = 96
+
+    /// Ordnet die Widgets in der gespeicherten Reihenfolge ein, jedes an die
+    /// erste Stelle, an die es passt.
+    ///
+    /// Der Reihe nach von links oben zu suchen statt stur hintereinander zu
+    /// setzen ist der ganze Unterschied: neben einem 2×2-Widget bleiben rechts
+    /// zwei 1×1-Plätze frei, und ein Verfahren, das immer nur hinten anfügt,
+    /// lässt sie dauerhaft leer.
+    public static func resolve(_ placements: [WidgetPlacement]) -> [ResolvedPlacement] {
+        var occupied = Set<GridCell>()
+        var resolved: [ResolvedPlacement] = []
+
+        for placement in placements {
+            let span = placement.size
+            // Zu breit für das Raster: einpassen statt verwerfen. Ein Widget
+            // verschwinden zu lassen wäre für den Nutzer nicht erklärbar.
+            let columnSpan = min(span.columnSpan, columns)
+
+            guard let cell = firstFreeCell(columnSpan: columnSpan,
+                                           rowSpan: span.rowSpan,
+                                           occupied: occupied) else { continue }
+
+            for row in cell.row..<(cell.row + span.rowSpan) {
+                for column in cell.column..<(cell.column + columnSpan) {
+                    occupied.insert(GridCell(row: row, column: column))
+                }
+            }
+            resolved.append(ResolvedPlacement(placement: placement,
+                                              row: cell.row,
+                                              column: cell.column))
+        }
+        return resolved
+    }
+
+    private static func firstFreeCell(columnSpan: Int,
+                                      rowSpan: Int,
+                                      occupied: Set<GridCell>) -> GridCell? {
+        let maxRow = (occupied.map(\.row).max() ?? -1) + rowSpan + 1
+
+        for row in 0...maxRow {
+            for column in 0...(columns - columnSpan) {
+                let fits = (row..<(row + rowSpan)).allSatisfy { r in
+                    (column..<(column + columnSpan)).allSatisfy { c in
+                        !occupied.contains(GridCell(row: r, column: c))
+                    }
+                }
+                if fits { return GridCell(row: row, column: column) }
+            }
+        }
+        return nil
+    }
+
+    /// Die Größe, die das Panel für dieses Layout braucht.
+    public static func panelSize(for resolved: [ResolvedPlacement]) -> CGSize {
+        let spacing = Onyx.Metric.tileSpacing
+        let padding = Onyx.Metric.panelPadding
+
+        let rows = resolved.map { $0.row + $0.rowSpan }.max() ?? 1
+        let usedRows = max(rows, 1)
+
+        return CGSize(
+            width: CGFloat(columns) * cellSize + CGFloat(columns - 1) * spacing + 2 * padding,
+            height: CGFloat(usedRows) * cellSize + CGFloat(usedRows - 1) * spacing + 2 * padding)
+    }
+
+    /// Der Rahmen eines Widgets innerhalb des Panels, in SwiftUI-Koordinaten
+    /// (Ursprung oben links).
+    public static func frame(for item: ResolvedPlacement, in panelSize: CGSize) -> CGRect {
+        let spacing = Onyx.Metric.tileSpacing
+        let padding = Onyx.Metric.panelPadding
+
+        let x = padding + CGFloat(item.column) * (cellSize + spacing)
+        let y = padding + CGFloat(item.row) * (cellSize + spacing)
+        let width = CGFloat(item.columnSpan) * cellSize + CGFloat(item.columnSpan - 1) * spacing
+        let height = CGFloat(item.rowSpan) * cellSize + CGFloat(item.rowSpan - 1) * spacing
+
+        return CGRect(x: x, y: y, width: width, height: height)
+    }
+}

Packages/OnyxKit/Sources/OnyxWidgetKit/LayoutStore.swift

@@ -0,0 +1,76 @@
+import Foundation
+
+/// Liest und schreibt die Widget-Anordnung.
+///
+/// Die Datei überlebt App-Updates und kann deshalb Widgets nennen, die es nicht
+/// mehr gibt. Solche Einträge fallen beim Laden weg. Was aber **nicht** passieren
+/// darf: dass ein Nutzer nach einem Update vor einem leeren Panel sitzt, ohne dass
+/// es dafür einen erkennbaren Grund gibt. Deshalb der Unterschied zwischen
+/// „absichtlich leer" und „nichts Brauchbares übrig".
+public struct LayoutStore: Sendable {
+
+    private struct Document: Codable {
+        var version: Int
+        var placements: [WidgetPlacement]
+    }
+
+    private static let currentVersion = 1
+
+    public let url: URL
+
+    public init(url: URL) {
+        self.url = url
+    }
+
+    /// Der Normalfall: `~/Library/Application Support/Onyx/layout.json`
+    public static func standard() -> LayoutStore {
+        let base = FileManager.default
+            .urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+            .appendingPathComponent("Onyx", isDirectory: true)
+        return LayoutStore(url: base.appendingPathComponent("layout.json"))
+    }
+
+    public func save(_ placements: [WidgetPlacement]) throws {
+        try FileManager.default.createDirectory(at: url.deletingLastPathComponent(),
+                                                withIntermediateDirectories: true)
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        let document = Document(version: Self.currentVersion, placements: placements)
+        try encoder.encode(document).write(to: url, options: .atomic)
+    }
+
+    public func load(knownWidgetIDs: Set<String>) -> [WidgetPlacement] {
+        guard let data = try? Data(contentsOf: url),
+              let document = try? JSONDecoder().decode(Document.self, from: data) else {
+            // Keine Datei oder unlesbar — beides führt zum Standardlayout.
+            return Self.defaultLayout(knownWidgetIDs: knownWidgetIDs)
+        }
+
+        let surviving = document.placements.filter { knownWidgetIDs.contains($0.widgetID) }
+
+        // Eine leere Datei ist eine Aussage: der Nutzer hat alle Widgets entfernt.
+        // Eine Datei, aus der nach dem Filtern nichts übrig bleibt, ist dagegen
+        // ein Zeichen dafür, dass sich die Kennungen geändert haben — hier wäre
+        // ein leeres Panel eine stille Fehlfunktion.
+        if surviving.isEmpty && !document.placements.isEmpty {
+            return Self.defaultLayout(knownWidgetIDs: knownWidgetIDs)
+        }
+        return surviving
+    }
+
+    /// Womit Onyx beim ersten Start dasteht. Bewusst zurückhaltend: lieber
+    /// wenige Widgets, die sofort etwas zeigen, als ein volles Panel, das
+    /// erst konfiguriert werden will.
+    public static func defaultLayout(knownWidgetIDs: Set<String>) -> [WidgetPlacement] {
+        let preferred: [(String, WidgetSize)] = [
+            ("calendar", .large),
+            ("weather", .medium),
+            ("cpu", .small),
+            ("battery", .small),
+            ("media", .wide),
+        ]
+        return preferred
+            .filter { knownWidgetIDs.contains($0.0) }
+            .map { WidgetPlacement(widgetID: $0.0, size: $0.1) }
+    }
+}

Packages/OnyxKit/Sources/OnyxWidgetKit/OnyxWidget.swift

@@ -0,0 +1,50 @@
+import SwiftUI
+
+/// Ein Widget im Notch-Panel.
+///
+/// Das Panel kennt ausschließlich dieses Protokoll. Ein neues Widget kommt
+/// dazu, indem es sich bei der Registry meldet — am Panel selbst ändert sich
+/// dafür keine Zeile.
+@MainActor
+public protocol OnyxWidget: Identifiable, Sendable {
+    /// Stabil über App-Versionen hinweg: dieser Wert steht in der Layout-Datei.
+    var id: String { get }
+    /// Lokalisierter Name für die Einstellungen.
+    var displayName: String { get }
+    var symbolName: String { get }
+
+    /// Welche Größen dieses Widget sinnvoll ausfüllen kann.
+    var supportedSizes: [WidgetSize] { get }
+
+    @ViewBuilder func makeView(size: WidgetSize) -> AnyView
+    /// Einstellungen dieses Widgets, falls es welche hat.
+    @ViewBuilder func makeSettingsView() -> AnyView?
+}
+
+public extension OnyxWidget {
+    func makeSettingsView() -> AnyView? { nil }
+}
+
+/// Alle bekannten Widgets. Die App füllt sie beim Start.
+@MainActor
+public final class WidgetRegistry {
+    public static let shared = WidgetRegistry()
+
+    private var widgets: [String: any OnyxWidget] = [:]
+    private var order: [String] = []
+
+    private init() {}
+
+    public func register(_ widget: any OnyxWidget) {
+        if widgets[widget.id] == nil { order.append(widget.id) }
+        widgets[widget.id] = widget
+    }
+
+    public func widget(id: String) -> (any OnyxWidget)? { widgets[id] }
+
+    /// In Registrierungsreihenfolge — das ist auch die Reihenfolge in den
+    /// Einstellungen.
+    public var all: [any OnyxWidget] { order.compactMap { widgets[$0] } }
+
+    public func contains(_ id: String) -> Bool { widgets[id] != nil }
+}

Packages/OnyxKit/Sources/OnyxWidgetKit/Placeholder.swift

@@ -1 +0,0 @@
-// OnyxWidgetKit

Packages/OnyxKit/Sources/OnyxWidgetKit/WidgetGrid.swift

@@ -0,0 +1,56 @@
+import SwiftUI
+import OnyxDesign
+
+/// Zeichnet ein aufgelöstes Layout.
+///
+/// Die Positionen kommen aus `LayoutEngine`, nicht aus einem SwiftUI-Grid. Ein
+/// `LazyVGrid` kann keine Kacheln über zwei Zeilen führen, und genau das braucht
+/// der Mini-Monat.
+public struct WidgetGrid: View {
+
+    private let resolved: [ResolvedPlacement]
+    private let panelSize: CGSize
+
+    public init(placements: [WidgetPlacement]) {
+        self.resolved = LayoutEngine.resolve(placements)
+        self.panelSize = LayoutEngine.panelSize(for: resolved)
+    }
+
+    public var body: some View {
+        ZStack(alignment: .topLeading) {
+            ForEach(resolved) { item in
+                let frame = LayoutEngine.frame(for: item, in: panelSize)
+
+                widgetView(for: item)
+                    .frame(width: frame.width, height: frame.height)
+                    .offset(x: frame.minX, y: frame.minY)
+            }
+        }
+        .frame(width: panelSize.width, height: panelSize.height, alignment: .topLeading)
+    }
+
+    @ViewBuilder
+    private func widgetView(for item: ResolvedPlacement) -> some View {
+        if let widget = WidgetRegistry.shared.widget(id: item.placement.widgetID) {
+            OnyxTile { widget.makeView(size: item.placement.size) }
+        } else {
+            // Sollte nach dem Filtern in LayoutStore nicht vorkommen. Falls doch,
+            // ist eine sichtbare Lücke mit Namen besser als ein stiller Ausfall.
+            OnyxTile {
+                VStack(spacing: 4) {
+                    Image(systemName: "questionmark.square.dashed")
+                    Text(item.placement.widgetID)
+                        .font(Onyx.Font.caption)
+                }
+                .foregroundStyle(Onyx.Color.textTertiary)
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+            }
+        }
+    }
+
+    /// Die Größe, die das Panel für dieses Layout braucht — der Controller
+    /// stellt das Fenster darauf ein.
+    public static func panelSize(for placements: [WidgetPlacement]) -> CGSize {
+        LayoutEngine.panelSize(for: LayoutEngine.resolve(placements))
+    }
+}