claudecode-omc 5.6.6 → 5.6.8

package/.local/skills/swiftui-expert-skill/references/macos-window-styling.md

@@ -0,0 +1,303 @@
+# macOS Window & Toolbar Styling Reference
+
+> Window configuration, toolbar styles, sizing, positioning, and navigation patterns specific to macOS SwiftUI apps.
+
+## Table of Contents
+
+- [Quick Lookup Table](#quick-lookup-table)
+- [Toolbar Styles](#toolbar-styles)
+- [Window Style](#window-style)
+- [Window Sizing](#window-sizing)
+- [MenuBarExtra Style (macOS-only)](#menubarextra-style-macos-only)
+- [Navigation Layout (macOS behavior)](#navigation-layout-macos-behavior)
+- [Commands & Keyboard](#commands--keyboard)
+- [Best Practices](#best-practices)
+
+---
+
+## Quick Lookup Table
+
+| API | Availability | macOS-Only? | Usage |
+|-----|-------------|:-----------:|-------|
+| `windowToolbarStyle(_:)` | macOS 11.0+ | Yes | Sets toolbar style: `.unified`, `.unifiedCompact`, `.expanded` |
+| `windowStyle(_:)` | macOS 11.0+ | No | Supports `.hiddenTitleBar` for chromeless windows |
+| `windowResizability(_:)` | macOS 13.0+ | No | Controls resize handle and green zoom button behavior |
+| `defaultSize(width:height:)` | macOS 13.0+ | No | Initial frame size when user creates a new window |
+| `defaultPosition(_:)` | macOS 13.0+ | No | Initial window position on screen |
+| `windowIdealPlacement(_:)` | macOS 15.0+ | No | Closure with display geometry for precise window positioning |
+| `menuBarExtraStyle(_:)` | macOS 13.0+ | Yes | Sets MenuBarExtra to `.menu` or `.window` style |
+| `NavigationSplitView` | macOS 13.0+ | No | Columns always visible side-by-side on macOS; translucent sidebar |
+| `Inspector` | macOS 14.0+ | No | Trailing-edge sidebar panel; resizable by dragging |
+
+---
+
+## Toolbar Styles
+
+### windowToolbarStyle (macOS-only)
+
+Controls how the toolbar and title bar are displayed. Applied to a scene.
+
+```swift
+@main
+struct MyApp: App {
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+        // Title bar and toolbar in a single row
+        .windowToolbarStyle(.unified)
+    }
+}
+```
+
+**Available styles:**
+
+| Style | Description |
+|-------|-------------|
+| `.automatic` | System default |
+| `.unified` | Title bar and toolbar in a single combined row |
+| `.unifiedCompact` | Same as unified but with reduced vertical height |
+| `.expanded` | Title bar displayed above the toolbar (more toolbar space) |
+
+```swift
+// Unified compact — minimal chrome
+.windowToolbarStyle(.unifiedCompact)
+
+// Expanded — title bar above toolbar
+.windowToolbarStyle(.expanded)
+
+// Unified with title hidden
+.windowToolbarStyle(.unified(showsTitle: false))
+```
+
+### Toolbar content
+
+```swift
+struct ContentView: View {
+    @State private var searchText = ""
+
+    var body: some View {
+        NavigationSplitView {
+            SidebarView()
+        } detail: {
+            DetailView()
+        }
+        .toolbar {
+            ToolbarItem(placement: .automatic) {
+                Button(action: addItem) {
+                    Label("Add", systemImage: "plus")
+                }
+            }
+        }
+        .searchable(text: $searchText, placement: .sidebar)
+    }
+}
+```
+
+---
+
+## Window Style
+
+### windowStyle
+
+Set the visual style of a window. Use `.hiddenTitleBar` for chromeless, immersive windows.
+
+```swift
+// Standard title bar (default)
+WindowGroup {
+    ContentView()
+}
+.windowStyle(.titleBar)
+
+// Hidden title bar — chromeless window
+WindowGroup {
+    ContentView()
+}
+.windowStyle(.hiddenTitleBar)
+```
+
+> **Use case:** `.hiddenTitleBar` is useful for media players, custom-chrome apps, or immersive experiences where the standard title bar is unwanted.
+
+---
+
+## Window Sizing
+
+### windowResizability, defaultSize, defaultPosition
+
+These modifiers work together to configure window sizing and placement:
+
+```swift
+WindowGroup {
+    ContentView()
+        .frame(minWidth: 600, minHeight: 400)
+}
+.defaultSize(width: 900, height: 600)
+.defaultPosition(.center)
+.windowResizability(.contentMinSize)
+```
+
+**`windowResizability` options:**
+
+| Value | Behavior |
+|-------|----------|
+| `.automatic` | System decides resize behavior |
+| `.contentSize` | Fixed to content size; no user resize; zoom button disabled |
+| `.contentMinSize` | Resizable with minimum based on content's `minWidth`/`minHeight` |
+
+**`defaultPosition` options:** `.center`, `.topLeading`, `.top`, `.topTrailing`, `.leading`, `.trailing`, `.bottomLeading`, `.bottom`, `.bottomTrailing`
+
+**Guidelines:**
+- Set `minWidth`/`minHeight` via `.frame()` on content, enforce with `.contentMinSize`
+- Use `.defaultSize()` for initial dimensions (larger than minimums)
+- `defaultSize` also accepts `CGSize`
+
+### windowIdealPlacement (macOS 15.0+)
+
+For precise programmatic positioning, use a closure with display geometry:
+
+```swift
+.windowIdealPlacement { context in
+    let screen = context.defaultDisplay.visibleArea
+    return WindowPlacement(x: screen.midX, y: screen.midY,
+                           width: screen.width / 2, height: screen.height)
+}
+```
+
+---
+
+## MenuBarExtra Style (macOS-only)
+
+Choose between dropdown menu and popover panel for `MenuBarExtra`.
+
+```swift
+// Dropdown menu (default)
+MenuBarExtra("Status", systemImage: "chart.bar") {
+    Button("Action") { /* ... */ }
+}
+.menuBarExtraStyle(.menu)
+
+// Popover panel with custom SwiftUI content
+MenuBarExtra("Status", systemImage: "chart.bar") {
+    DashboardView()
+}
+.menuBarExtraStyle(.window)
+```
+
+---
+
+## Navigation Layout (macOS behavior)
+
+### NavigationSplitView
+
+On macOS, `NavigationSplitView` displays columns side-by-side (never overlaid). The sidebar gets a translucent material background. Columns support variable-width resizing by the user.
+
+```swift
+NavigationSplitView {
+    List(items, selection: $selectedId) { item in
+        Text(item.name)
+    }
+    .navigationSplitViewColumnWidth(min: 180, ideal: 220, max: 300)
+} detail: {
+    DetailView(id: selectedId)
+}
+.navigationSplitViewStyle(.balanced)
+```
+
+Use the three-column variant (`sidebar` / `content` / `detail`) for master-detail-detail layouts. Customize column widths with `.navigationSplitViewColumnWidth(min:ideal:max:)`.
+
+### Inspector (macOS 14.0+)
+
+A trailing-edge panel for supplementary information. On macOS, it appears as a sidebar-style panel that can be resized by dragging its edge.
+
+```swift
+struct ContentView: View {
+    @State private var showInspector = false
+
+    var body: some View {
+        MainContent()
+            .inspector(isPresented: $showInspector) {
+                InspectorView()
+                    .inspectorColumnWidth(min: 200, ideal: 250, max: 400)
+            }
+            .toolbar {
+                ToolbarItem {
+                    Button {
+                        showInspector.toggle()
+                    } label: {
+                        Label("Inspector", systemImage: "info.circle")
+                    }
+                }
+            }
+    }
+}
+```
+
+---
+
+## Commands & Keyboard
+
+### Commands, CommandGroup, CommandMenu
+
+Define menu bar commands. On macOS, these populate the menu bar directly. On iOS, they create key commands.
+
+```swift
+.commands {
+    CommandMenu("Tools") {
+        Button("Run Analysis") { /* ... */ }
+            .keyboardShortcut("r", modifiers: [.command, .shift])
+    }
+    CommandGroup(after: .newItem) {
+        Button("New From Template...") { /* ... */ }
+    }
+}
+```
+
+**`CommandGroup` placement options:** `.replacing(_:)` replaces a system group, `.before(_:)` / `.after(_:)` inserts adjacent to it. Common placements: `.newItem`, `.saveItem`, `.help`, `.toolbar`, `.sidebar`.
+
+### KeyboardShortcut
+
+On macOS, shortcuts are displayed alongside menu items and in button tooltips on hover.
+
+```swift
+Button("Save") {
+    save()
+}
+.keyboardShortcut("s", modifiers: .command)
+
+Button("Delete") {
+    delete()
+}
+.keyboardShortcut(.delete, modifiers: .command)
+```
+
+### openWindow
+
+Programmatically open a window. If the target window is already open, brings it to the front.
+
+```swift
+struct ToolbarActions: View {
+    @Environment(\.openWindow) private var openWindow
+
+    var body: some View {
+        Button("Connection Doctor") {
+            openWindow(id: "connection-doctor")
+        }
+
+        Button("Show Message") {
+            openWindow(value: message.id)  // Type-matched to WindowGroup
+        }
+    }
+}
+```
+
+---
+
+## Best Practices
+
+- **Use `.unified` or `.unifiedCompact`** for most apps — `.expanded` only when you need many toolbar items
+- **Set min frame sizes on content** and use `.windowResizability(.contentMinSize)` to enforce them
+- **Always provide `defaultSize`** so new windows start at a reasonable size
+- **Use `NavigationSplitView`** for sidebar navigation — not `HSplitView`
+- **Use `Inspector`** for supplementary panels — it integrates with the toolbar automatically
+- **Define `Commands`** for all repeatable actions — users expect keyboard shortcuts on macOS
+- **Use `#if os(macOS)`** to wrap macOS-only window configuration in multiplatform projects

package/.local/skills/swiftui-expert-skill/references/performance-patterns.md

@@ -0,0 +1,403 @@
+# SwiftUI Performance Patterns Reference
+
+## Table of Contents
+
+- [Performance Optimization](#performance-optimization)
+- [Anti-Patterns](#anti-patterns)
+- [Summary Checklist](#summary-checklist)
+
+## Performance Optimization
+
+### 1. Avoid Redundant State Updates
+
+SwiftUI doesn't compare values before triggering updates:
+
+```swift
+// BAD - triggers update even if value unchanged
+.onReceive(publisher) { value in
+    self.currentValue = value  // Always triggers body re-evaluation
+}
+
+// GOOD - only update when different
+.onReceive(publisher) { value in
+    if self.currentValue != value {
+        self.currentValue = value
+    }
+}
+```
+
+### 2. Optimize Hot Paths
+
+Hot paths are frequently executed code (scroll handlers, animations, gestures):
+
+```swift
+// BAD - updates state on every scroll position change
+.onPreferenceChange(ScrollOffsetKey.self) { offset in
+    shouldShowTitle = offset.y <= -32  // Fires constantly during scroll!
+}
+
+// GOOD - only update when threshold crossed
+.onPreferenceChange(ScrollOffsetKey.self) { offset in
+    let shouldShow = offset.y <= -32
+    if shouldShow != shouldShowTitle {
+        shouldShowTitle = shouldShow  // Fires only when crossing threshold
+    }
+}
+```
+
+### 3. Pass Only What Views Need
+
+**Avoid passing large "config" or "context" objects.** Pass only the specific values each view needs.
+
+```swift
+// Good - pass specific values
+ThemeSelector(theme: config.theme)
+FontSizeSlider(fontSize: config.fontSize)
+
+// Avoid - passing entire config (creates broad dependency)
+ThemeSelector(config: config)  // Notified of ALL config changes
+```
+
+With `ObservableObject`, any `@Published` change triggers all observers. With `@Observable`, views update only when accessed properties change, but passing entire objects still creates broader dependencies than necessary.
+
+### 4. Use Equatable Views
+
+For views with expensive bodies, conform to `Equatable`:
+
+```swift
+struct ExpensiveView: View, Equatable {
+    let data: SomeData
+
+    static func == (lhs: Self, rhs: Self) -> Bool {
+        lhs.data.id == rhs.data.id  // Custom equality check
+    }
+
+    var body: some View {
+        // Expensive computation
+    }
+}
+
+// Usage
+ExpensiveView(data: data)
+    .equatable()  // Use custom equality
+```
+
+**Caution**: If you add new state or dependencies to your view, remember to update your `==` function!
+
+### 5. POD Views for Fast Diffing
+
+**POD (Plain Old Data) views use `memcmp` for fastest diffing.** A view is POD if it only contains simple value types and no property wrappers.
+
+```swift
+// POD view - fastest diffing
+struct FastView: View {
+    let title: String
+    let count: Int
+    
+    var body: some View {
+        Text("\(title): \(count)")
+    }
+}
+
+// Non-POD view - uses reflection or custom equality
+struct SlowerView: View {
+    let title: String
+    @State private var isExpanded = false  // Property wrapper makes it non-POD
+    
+    var body: some View {
+        Text(title)
+    }
+}
+```
+
+**Advanced Pattern**: Wrap expensive non-POD views in POD parent views:
+
+```swift
+// POD wrapper for fast diffing
+struct ExpensiveView: View {
+    let value: Int
+    
+    var body: some View {
+        ExpensiveViewInternal(value: value)
+    }
+}
+
+// Internal view with state
+private struct ExpensiveViewInternal: View {
+    let value: Int
+    @State private var item: Item?
+    
+    var body: some View {
+        // Expensive rendering
+    }
+}
+```
+
+**Why**: The POD parent uses fast `memcmp` comparison. Only when `value` changes does the internal view get diffed.
+
+### 6. Lazy Loading
+
+Use lazy containers for large collections:
+
+```swift
+// BAD - creates all views immediately
+ScrollView {
+    VStack {
+        ForEach(items) { item in
+            ExpensiveRow(item: item)
+        }
+    }
+}
+
+// GOOD - creates views on demand
+ScrollView {
+    LazyVStack {
+        ForEach(items) { item in
+            ExpensiveRow(item: item)
+        }
+    }
+}
+```
+
+**iOS 26+ note**: Nested scroll views containing lazy stacks now automatically defer loading their children until they are about to appear, matching the behavior of top-level lazy stacks. This benefits patterns like horizontal photo carousels inside a vertical scroll view.
+
+> Source: "What's new in SwiftUI" (WWDC25, session 256)
+
+### 7. Task Cancellation
+
+Cancel async work when view disappears:
+
+```swift
+struct DataView: View {
+    @State private var data: [Item] = []
+
+    var body: some View {
+        List(data) { item in
+            Text(item.name)
+        }
+        .task {
+            // Automatically cancelled when view disappears
+            data = await fetchData()
+        }
+    }
+}
+```
+
+### 8. Debug View Updates
+
+**Use `Self._printChanges()` or `Self._logChanges()` to debug unexpected view updates.**
+
+```swift
+struct DebugView: View {
+    @State private var count = 0
+    @State private var name = ""
+    
+    var body: some View {
+        #if DEBUG
+        let _ = Self._logChanges()  // Xcode 15.1+: logs to com.apple.SwiftUI subsystem
+        #endif
+        
+        VStack {
+            Text("Count: \(count)")
+            Text("Name: \(name)")
+        }
+    }
+}
+```
+
+- `Self._printChanges()`: Prints which properties changed to standard output.
+- `Self._logChanges()` (iOS 17+): Logs to the `com.apple.SwiftUI` subsystem with category "Changed Body Properties", using `os_log` for structured output.
+
+Both print `@self` when the view value itself changed and `@identity` when the view's persistent data was recycled.
+
+**Why**: This helps identify which state changes are causing view updates. Isolating redraw triggers into single-responsibility subviews is often the fix -- extracting a subview means SwiftUI can skip its body when its inputs haven't changed.
+
+### 9. Eliminate Unnecessary Dependencies
+
+**Narrow state scope to reduce update fan-out.** Instead of passing an entire `@Observable` model to a row view (which creates a dependency on all accessed properties), pass only the specific values the view needs as `let` properties.
+
+```swift
+// Bad - broad dependency on entire model
+struct ItemRow: View {
+    @Environment(AppModel.self) private var model
+    let item: Item
+    var body: some View { Text(item.name).foregroundStyle(model.theme.primaryColor) }
+}
+
+// Good - narrow dependency
+struct ItemRow: View {
+    let item: Item
+    let themeColor: Color
+    var body: some View { Text(item.name).foregroundStyle(themeColor) }
+}
+```
+
+**Avoid storing frequently-changing values in the environment.** Even when a view doesn't read the changed key, SwiftUI still checks all environment readers. This cost adds up with many views and frequent updates (geometry values, timers).
+
+> Source: "Optimize SwiftUI performance with Instruments" (WWDC25, session 306)
+
+### 10. @Observable Dependency Granularity
+
+**Consider per-item `@Observable` state holders (one per row/item) to narrow update scope.** When multiple list items share a dependency on the same `@Observable` array, changing one element causes all items to re-evaluate their bodies.
+
+```swift
+// BAD - all item views depend on the full favorites array
+@Observable
+class ModelData {
+    var favorites: [Landmark] = []
+
+    func isFavorite(_ landmark: Landmark) -> Bool {
+        favorites.contains(landmark)
+    }
+}
+
+struct LandmarkRow: View {
+    let landmark: Landmark
+    @Environment(ModelData.self) private var model
+
+    var body: some View {
+        HStack {
+            Text(landmark.name)
+            if model.isFavorite(landmark) {
+                Image(systemName: "heart.fill")
+            }
+        }
+    }
+}
+
+// GOOD - each item has its own observable view model
+@Observable
+class LandmarkViewModel {
+    var isFavorite: Bool = false
+}
+
+struct LandmarkRow: View {
+    let landmark: Landmark
+    let viewModel: LandmarkViewModel
+
+    var body: some View {
+        HStack {
+            Text(landmark.name)
+            if viewModel.isFavorite {
+                Image(systemName: "heart.fill")
+            }
+        }
+    }
+}
+```
+
+**Why**: With the bad pattern, toggling one favorite marks the entire array as changed, causing every `LandmarkRow` to re-run its body. With per-item view models, only the toggled item's body runs.
+
+> Source: "Optimize SwiftUI performance with Instruments" (WWDC25, session 306)
+
+### 11. Off-Main-Thread Closures
+
+**SwiftUI may call certain closures on a background thread for performance.** These closures must be `Sendable` and should avoid accessing `@MainActor`-isolated state directly. Instead, capture needed values in the closure's capture list.
+
+Closures that may run off the main thread:
+- `Shape.path(in:)`
+- `visualEffect` closure
+- `Layout` protocol methods
+- `onGeometryChange` transform closure
+
+```swift
+// BAD - accessing @MainActor state directly
+.visualEffect { content, geometry in
+    content.blur(radius: self.pulse ? 5 : 0)  // Compiler error: @MainActor isolated
+}
+
+// GOOD - capture the value
+.visualEffect { [pulse] content, geometry in
+    content.blur(radius: pulse ? 5 : 0)
+}
+```
+
+> Source: "Explore concurrency in SwiftUI" (WWDC25, session 266)
+
+### 12. Common Performance Issues
+
+**Be aware of common performance bottlenecks in SwiftUI:**
+
+- View invalidation storms from broad state changes
+- Unstable identity in lists causing excessive diffing
+- Heavy work in `body` (formatting, sorting, image decoding)
+- Layout thrash from deep stacks or preference chains
+
+**When performance issues arise**, suggest the user profile with Instruments (SwiftUI template) to identify specific bottlenecks.
+
+## Anti-Patterns
+
+### 1. Creating Objects in Body
+
+```swift
+// BAD - creates new formatter every body call
+var body: some View {
+    let formatter = DateFormatter()
+    formatter.dateStyle = .long
+    return Text(formatter.string(from: date))
+}
+
+// GOOD - static or stored formatter
+private static let dateFormatter: DateFormatter = {
+    let f = DateFormatter()
+    f.dateStyle = .long
+    return f
+}()
+
+var body: some View {
+    Text(Self.dateFormatter.string(from: date))
+}
+```
+
+### 2. Heavy Computation in Body
+
+**Keep view body simple and pure.** Avoid side effects, dispatching, or complex logic.
+
+```swift
+// BAD - sorts array every body call
+var body: some View {
+    List(items.sorted { $0.name < $1.name }) { item in Text(item.name) }
+}
+
+// GOOD - compute once, update via onChange or a computed property in the model
+@State private var sortedItems: [Item] = []
+
+var body: some View {
+    List(sortedItems) { item in Text(item.name) }
+        .onChange(of: items) { _, newItems in
+            sortedItems = newItems.sorted { $0.name < $1.name }
+        }
+}
+```
+
+Move sorting, filtering, and formatting into models or computed properties. The `body` should be a pure structural representation of state.
+
+### 3. Unnecessary State
+
+```swift
+// BAD - derived state stored separately
+@State private var items: [Item] = []
+@State private var itemCount: Int = 0  // Unnecessary!
+
+// GOOD - compute derived values
+@State private var items: [Item] = []
+
+var itemCount: Int { items.count }  // Computed property
+```
+
+## Summary Checklist
+
+- [ ] State updates check for value changes before assigning
+- [ ] Hot paths minimize state updates
+- [ ] Pass only needed values to views (avoid large config objects)
+- [ ] Large lists use `LazyVStack`/`LazyHStack`
+- [ ] No object creation in `body`
+- [ ] Heavy computation moved out of `body`
+- [ ] Body kept simple and pure (no side effects)
+- [ ] Derived state computed, not stored
+- [ ] Use `Self._logChanges()` or `Self._printChanges()` to debug unexpected updates
+- [ ] Equatable conformance for expensive views (when appropriate)
+- [ ] Consider POD view wrappers for advanced optimization
+- [ ] Consider using granular @Observable dependencies for list items (smaller observable units per row when it measurably reduces updates)
+- [ ] Frequently-changing values not stored in the environment
+- [ ] Sendable closures (Shape, visualEffect, Layout) capture values instead of accessing @MainActor state