@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/swiftui-expert-skill/references/performance-patterns.md

@@ -0,0 +1,377 @@
+# SwiftUI Performance Patterns Reference
+
+## 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
+@Observable
+@MainActor
+final class AppConfig {
+    var theme: Theme
+    var fontSize: CGFloat
+    var notifications: Bool
+}
+
+struct SettingsView: View {
+    @State private var config = AppConfig()
+    
+    var body: some View {
+        VStack {
+            ThemeSelector(theme: config.theme)
+            FontSizeSlider(fontSize: config.fontSize)
+        }
+    }
+}
+
+// Avoid - passing entire config
+struct SettingsView: View {
+    @State private var config = AppConfig()
+    
+    var body: some View {
+        VStack {
+            ThemeSelector(config: config)  // Gets notified of ALL config changes
+            FontSizeSlider(config: config)  // Gets notified of ALL config changes
+        }
+    }
+}
+```
+
+**Why**: When using `ObservableObject`, any `@Published` property change triggers updates in all views observing the object. With `@Observable`, views update when properties they access change, but passing entire objects still creates unnecessary dependencies.
+
+### 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)
+        }
+    }
+}
+```
+
+### 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()` to debug unexpected view updates.**
+
+```swift
+struct DebugView: View {
+    @State private var count = 0
+    @State private var name = ""
+    
+    var body: some View {
+        let _ = Self._printChanges()  // Prints what caused body to be called
+        
+        VStack {
+            Text("Count: \(count)")
+            Text("Name: \(name)")
+        }
+    }
+}
+```
+
+**Why**: This helps identify which state changes are causing view updates. Even if a parent updates, a child's body shouldn't be called if the child's dependencies didn't change.
+
+### 9. Eliminate Unnecessary Dependencies
+
+**Narrow state scope to reduce update fan-out.**
+
+```swift
+// Bad - broad dependency
+@Observable
+@MainActor
+final class AppModel {
+    var items: [Item] = []
+    var settings: Settings = .init()
+    var theme: Theme = .light
+}
+
+struct ItemRow: View {
+    @Environment(AppModel.self) private var model
+    let item: Item
+    
+    var body: some View {
+        // Updates when ANY property of model changes
+        Text(item.name)
+            .foregroundStyle(model.theme.primaryColor)
+    }
+}
+
+// Good - narrow dependency
+struct ItemRow: View {
+    let item: Item
+    let themeColor: Color  // Only depends on what it needs
+    
+    var body: some View {
+        Text(item.name)
+            .foregroundStyle(themeColor)
+    }
+}
+```
+
+**Why**: With `ObservableObject`, any `@Published` property change triggers all observers. With `@Observable`, views update when accessed properties change, but passing entire models still creates broader dependencies than necessary.
+
+### 10. 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, store result
+@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 }
+    }
+}
+
+// Better - compute in model
+@Observable
+@MainActor
+final class ItemsViewModel {
+    var items: [Item] = []
+    
+    var sortedItems: [Item] {
+        items.sorted { $0.name < $1.name }
+    }
+    
+    func loadItems() async {
+        items = await fetchItems()
+    }
+}
+
+struct ItemsView: View {
+    @State private var viewModel = ItemsViewModel()
+    
+    var body: some View {
+        List(viewModel.sortedItems) { item in
+            Text(item.name)
+        }
+        .task {
+            await viewModel.loadItems()
+        }
+    }
+}
+```
+
+**Why**: Complex logic in `body` slows down view updates and can cause frame drops. 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._printChanges()` to debug unexpected updates
+- [ ] Equatable conformance for expensive views (when appropriate)
+- [ ] Consider POD view wrappers for advanced optimization

package/dist/template/.opencode/skill/swiftui-expert-skill/references/scroll-patterns.md

@@ -0,0 +1,305 @@
+# SwiftUI ScrollView Patterns Reference
+
+## ScrollView Modifiers
+
+### Hiding Scroll Indicators
+
+**Use `.scrollIndicators(.hidden)` modifier instead of initializer parameter.**
+
+```swift
+// Modern (Correct)
+ScrollView {
+    content
+}
+.scrollIndicators(.hidden)
+
+// Legacy (Avoid)
+ScrollView(showsIndicators: false) {
+    content
+}
+```
+
+## ScrollViewReader for Programmatic Scrolling
+
+**Use `ScrollViewReader` for scroll-to-top, scroll-to-bottom, and anchor-based jumps.**
+
+```swift
+struct ChatView: View {
+    @State private var messages: [Message] = []
+    private let bottomID = "bottom"
+    
+    var body: some View {
+        ScrollViewReader { proxy in
+            ScrollView {
+                LazyVStack {
+                    ForEach(messages) { message in
+                        MessageRow(message: message)
+                            .id(message.id)
+                    }
+                    Color.clear
+                        .frame(height: 1)
+                        .id(bottomID)
+                }
+            }
+            .onChange(of: messages.count) { _, _ in
+                withAnimation {
+                    proxy.scrollTo(bottomID, anchor: .bottom)
+                }
+            }
+            .onAppear {
+                proxy.scrollTo(bottomID, anchor: .bottom)
+            }
+        }
+    }
+}
+```
+
+### Scroll-to-Top Pattern
+
+```swift
+struct FeedView: View {
+    @State private var items: [Item] = []
+    @State private var scrollToTop = false
+    private let topID = "top"
+    
+    var body: some View {
+        ScrollViewReader { proxy in
+            ScrollView {
+                LazyVStack {
+                    Color.clear
+                        .frame(height: 1)
+                        .id(topID)
+                    
+                    ForEach(items) { item in
+                        ItemRow(item: item)
+                    }
+                }
+            }
+            .onChange(of: scrollToTop) { _, shouldScroll in
+                if shouldScroll {
+                    withAnimation {
+                        proxy.scrollTo(topID, anchor: .top)
+                    }
+                    scrollToTop = false
+                }
+            }
+        }
+    }
+}
+```
+
+**Why**: `ScrollViewReader` provides programmatic scroll control with stable anchors. Always use stable IDs and explicit animations.
+
+## Scroll Position Tracking
+
+### Basic Scroll Position
+
+**Avoid** - Storing scroll position directly triggers view updates on every scroll frame:
+
+```swift
+// ❌ Bad Practice - causes unnecessary re-renders
+struct ContentView: View {
+    @State private var scrollPosition: CGFloat = 0
+
+    var body: some View {
+        ScrollView {
+            content
+                .background(
+                    GeometryReader { geometry in
+                        Color.clear
+                            .preference(
+                                key: ScrollOffsetPreferenceKey.self,
+                                value: geometry.frame(in: .named("scroll")).minY
+                            )
+                    }
+                )
+        }
+        .coordinateSpace(name: "scroll")
+        .onPreferenceChange(ScrollOffsetPreferenceKey.self) { value in
+            scrollPosition = value
+        }
+    }
+}
+```
+
+**Preferred** - Check scroll position and update a flag based on thresholds for smoother, more efficient scrolling:
+
+```swift
+// ✅ Good Practice - only updates state when crossing threshold
+struct ContentView: View {
+    @State private var startAnimation: Bool = false
+
+    var body: some View {
+        ScrollView {
+            content
+                .background(
+                    GeometryReader { geometry in
+                        Color.clear
+                            .preference(
+                                key: ScrollOffsetPreferenceKey.self,
+                                value: geometry.frame(in: .named("scroll")).minY
+                            )
+                    }
+                )
+        }
+        .coordinateSpace(name: "scroll")
+        .onPreferenceChange(ScrollOffsetPreferenceKey.self) { value in
+            if value < -100 {
+                startAnimation = true
+            } else {
+                startAnimation = false
+            }
+        }
+    }
+}
+
+struct ScrollOffsetPreferenceKey: PreferenceKey {
+    static var defaultValue: CGFloat = 0
+    static func reduce(value: inout CGFloat, nextValue: () -> CGFloat) {
+        value = nextValue()
+    }
+}
+```
+
+### Scroll-Based Header Visibility
+
+```swift
+struct ContentView: View {
+    @State private var showHeader = true
+    
+    var body: some View {
+        VStack(spacing: 0) {
+            if showHeader {
+                HeaderView()
+                    .transition(.move(edge: .top))
+            }
+            
+            ScrollView {
+                content
+                    .background(
+                        GeometryReader { geometry in
+                            Color.clear
+                                .preference(
+                                    key: ScrollOffsetPreferenceKey.self,
+                                    value: geometry.frame(in: .named("scroll")).minY
+                                )
+                        }
+                    )
+            }
+            .coordinateSpace(name: "scroll")
+            .onPreferenceChange(ScrollOffsetPreferenceKey.self) { offset in
+                if offset < -50 { // Scrolling down
+                   withAnimation { showHeader = false }
+                } else if offset > 50 { // Scrolling up
+                  withAnimation { showHeader = true }
+                }
+            }
+        }
+    }
+}
+```
+
+## Scroll Transitions and Effects
+
+> **iOS 17+**: All APIs in this section require iOS 17 or later.
+
+### Scroll-Based Opacity
+
+```swift
+struct ParallaxView: View {
+    var body: some View {
+        ScrollView {
+            LazyVStack(spacing: 20) {
+                ForEach(items) { item in
+                    ItemCard(item: item)
+                        .visualEffect { content, geometry in
+                            let frame = geometry.frame(in: .scrollView)
+                            let distance = min(0, frame.minY)
+                            return content
+                                .opacity(1 + distance / 200)
+                        }
+                }
+            }
+        }
+    }
+}
+```
+
+### Parallax Effect
+
+```swift
+struct ParallaxHeader: View {
+    var body: some View {
+        ScrollView {
+            VStack(spacing: 0) {
+                Image("hero")
+                    .resizable()
+                    .aspectRatio(contentMode: .fill)
+                    .frame(height: 300)
+                    .visualEffect { content, geometry in
+                        let offset = geometry.frame(in: .scrollView).minY
+                        return content
+                            .offset(y: offset > 0 ? -offset * 0.5 : 0)
+                    }
+                    .clipped()
+                
+                ContentView()
+            }
+        }
+    }
+}
+```
+
+## Scroll Target Behavior
+
+> **iOS 17+**: All APIs in this section require iOS 17 or later.
+
+### Paging ScrollView
+
+```swift
+struct PagingView: View {
+    var body: some View {
+        ScrollView(.horizontal) {
+            LazyHStack(spacing: 0) {
+                ForEach(pages) { page in
+                    PageView(page: page)
+                        .containerRelativeFrame(.horizontal)
+                }
+            }
+            .scrollTargetLayout()
+        }
+        .scrollTargetBehavior(.paging)
+    }
+}
+```
+
+### Snap to Items
+
+```swift
+struct SnapScrollView: View {
+    var body: some View {
+        ScrollView(.horizontal) {
+            LazyHStack(spacing: 16) {
+                ForEach(items) { item in
+                    ItemCard(item: item)
+                        .frame(width: 280)
+                }
+            }
+            .scrollTargetLayout()
+        }
+        .scrollTargetBehavior(.viewAligned)
+        .contentMargins(.horizontal, 20)
+    }
+}
+```
+
+## Summary Checklist
+
+- [ ] Use `.scrollIndicators(.hidden)` instead of initializer parameter
+- [ ] Use `ScrollViewReader` with stable IDs for programmatic scrolling
+- [ ] Always use explicit animations with `scrollTo()`
+- [ ] Use `.visualEffect` for scroll-based visual changes
+- [ ] Use `.scrollTargetBehavior(.paging)` for paging behavior
+- [ ] Use `.scrollTargetBehavior(.viewAligned)` for snap-to-item behavior
+- [ ] Gate frequent scroll position updates by thresholds
+- [ ] Use preference keys for custom scroll position tracking