codexkit 1.0.0

package/.codex/skills/swiftui-expert-skill/references/image-optimization.md

@@ -0,0 +1,286 @@
+# SwiftUI Image Optimization Reference
+
+## AsyncImage Best Practices
+
+### Basic AsyncImage with Phase Handling
+
+```swift
+// Good - handles loading and error states
+AsyncImage(url: imageURL) { phase in
+    switch phase {
+    case .empty:
+        ProgressView()
+    case .success(let image):
+        image
+            .resizable()
+            .aspectRatio(contentMode: .fit)
+    case .failure:
+        Image(systemName: "photo")
+            .foregroundStyle(.secondary)
+    @unknown default:
+        EmptyView()
+    }
+}
+.frame(width: 200, height: 200)
+```
+
+### AsyncImage with Custom Placeholder
+
+```swift
+struct ImageView: View {
+    let url: URL?
+    
+    var body: some View {
+        AsyncImage(url: url) { phase in
+            switch phase {
+            case .empty:
+                ZStack {
+                    Color.gray.opacity(0.2)
+                    ProgressView()
+                }
+            case .success(let image):
+                image
+                    .resizable()
+                    .aspectRatio(contentMode: .fill)
+            case .failure:
+                ZStack {
+                    Color.gray.opacity(0.2)
+                    Image(systemName: "exclamationmark.triangle")
+                        .foregroundStyle(.secondary)
+                }
+            @unknown default:
+                EmptyView()
+            }
+        }
+        .clipShape(.rect(cornerRadius: 12))
+    }
+}
+```
+
+### AsyncImage with Transition
+
+```swift
+AsyncImage(url: imageURL) { phase in
+    switch phase {
+    case .empty:
+        ProgressView()
+    case .success(let image):
+        image
+            .resizable()
+            .aspectRatio(contentMode: .fit)
+            .transition(.opacity)
+    case .failure:
+        Image(systemName: "photo")
+    @unknown default:
+        EmptyView()
+    }
+}
+.animation(.easeInOut, value: imageURL)
+```
+
+## Image Decoding and Downsampling (Optional Optimization)
+
+**When you encounter `UIImage(data:)` usage, consider suggesting image downsampling as a potential performance improvement**, especially for large images in lists or grids.
+
+### Current Pattern That Could Be Optimized
+
+```swift
+// Current pattern - decodes full image on main thread
+// Unsafe - force unwrap can crash if imageData is invalid
+Image(uiImage: UIImage(data: imageData)!)
+    .resizable()
+    .aspectRatio(contentMode: .fit)
+    .frame(width: 200, height: 200)
+```
+
+### Suggested Optimization Pattern
+
+```swift
+// Suggested optimization - decode and downsample off main thread
+struct OptimizedImageView: View {
+    let imageData: Data
+    let targetSize: CGSize
+    @State private var processedImage: UIImage?
+    
+    var body: some View {
+        Group {
+            if let processedImage {
+                Image(uiImage: processedImage)
+                    .resizable()
+                    .aspectRatio(contentMode: .fit)
+            } else {
+                ProgressView()
+            }
+        }
+        .task {
+            processedImage = await decodeAndDownsample(imageData, targetSize: targetSize)
+        }
+    }
+    
+    private func decodeAndDownsample(_ data: Data, targetSize: CGSize) async -> UIImage? {
+        await Task.detached {
+            guard let source = CGImageSourceCreateWithData(data as CFData, nil) else {
+                return nil
+            }
+            
+            let options: [CFString: Any] = [
+                kCGImageSourceThumbnailMaxPixelSize: max(targetSize.width, targetSize.height),
+                kCGImageSourceCreateThumbnailFromImageAlways: true,
+                kCGImageSourceCreateThumbnailWithTransform: true
+            ]
+            
+            guard let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
+                return nil
+            }
+            
+            return UIImage(cgImage: cgImage)
+        }.value
+    }
+}
+
+// Usage
+OptimizedImageView(
+    imageData: imageData,
+    targetSize: CGSize(width: 200, height: 200)
+)
+```
+
+### Reusable Image Downsampling Helper
+
+```swift
+actor ImageProcessor {
+    func downsample(data: Data, to targetSize: CGSize) -> UIImage? {
+        guard let source = CGImageSourceCreateWithData(data as CFData, nil) else {
+            return nil
+        }
+        
+        let maxDimension = max(targetSize.width, targetSize.height) * UIScreen.main.scale
+        
+        let options: [CFString: Any] = [
+            kCGImageSourceThumbnailMaxPixelSize: maxDimension,
+            kCGImageSourceCreateThumbnailFromImageAlways: true,
+            kCGImageSourceCreateThumbnailWithTransform: true,
+            kCGImageSourceShouldCache: false
+        ]
+        
+        guard let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
+            return nil
+        }
+        
+        return UIImage(cgImage: cgImage)
+    }
+}
+
+// Usage in view
+struct ImageView: View {
+    let imageData: Data
+    let targetSize: CGSize
+    @State private var image: UIImage?
+    
+    private let processor = ImageProcessor()
+    
+    var body: some View {
+        Group {
+            if let image {
+                Image(uiImage: image)
+                    .resizable()
+                    .aspectRatio(contentMode: .fit)
+            } else {
+                ProgressView()
+            }
+        }
+        .task {
+            image = await processor.downsample(data: imageData, to: targetSize)
+        }
+    }
+}
+```
+
+### When to Suggest This Optimization
+
+Mention this optimization when you see `UIImage(data:)` usage, particularly in:
+- Scrollable content (List, ScrollView with LazyVStack/LazyHStack)
+- Grid layouts with many images
+- Image galleries or carousels
+- Any scenario where large images are displayed at smaller sizes
+
+**Don't automatically apply it**—present it as an optional improvement for performance-sensitive scenarios.
+
+## SF Symbols
+
+### Using SF Symbols
+
+```swift
+// Basic symbol
+Image(systemName: "star.fill")
+    .foregroundStyle(.yellow)
+
+// With rendering mode
+Image(systemName: "heart.fill")
+    .symbolRenderingMode(.multicolor)
+
+// With variable color
+Image(systemName: "speaker.wave.3.fill")
+    .symbolRenderingMode(.hierarchical)
+    .foregroundStyle(.blue)
+
+// Animated symbols (iOS 17+)
+Image(systemName: "antenna.radiowaves.left.and.right")
+    .symbolEffect(.variableColor)
+```
+
+### SF Symbol Variants
+
+```swift
+// Circle variant
+Image(systemName: "star.circle.fill")
+
+// Square variant
+Image(systemName: "star.square.fill")
+
+// With badge
+Image(systemName: "folder.badge.plus")
+```
+
+## Image Rendering
+
+### ImageRenderer for Snapshots
+
+```swift
+// Render SwiftUI view to UIImage
+let renderer = ImageRenderer(content: myView)
+renderer.scale = UIScreen.main.scale
+
+if let uiImage = renderer.uiImage {
+    // Use the image (save, share, etc.)
+}
+
+// Render to CGImage
+if let cgImage = renderer.cgImage {
+    // Use CGImage
+}
+```
+
+### Rendering with Custom Size
+
+```swift
+let renderer = ImageRenderer(content: myView)
+renderer.proposedSize = ProposedViewSize(width: 400, height: 300)
+
+if let uiImage = renderer.uiImage {
+    // Image rendered at 400x300 points
+}
+```
+
+## Summary Checklist
+
+- [ ] Use `AsyncImage` with proper phase handling
+- [ ] Handle empty, success, and failure states
+- [ ] Consider downsampling for `UIImage(data:)` in performance-sensitive scenarios
+- [ ] Decode and downsample images off the main thread
+- [ ] Use appropriate target sizes for downsampling
+- [ ] Consider image caching for frequently accessed images
+- [ ] Use SF Symbols with appropriate rendering modes
+- [ ] Use `ImageRenderer` for rendering SwiftUI views to images
+
+**Performance Note**: Image downsampling is an optional optimization. Only suggest it when you encounter `UIImage(data:)` usage in performance-sensitive contexts like scrollable lists or grids.

package/.codex/skills/swiftui-expert-skill/references/layout-best-practices.md

@@ -0,0 +1,312 @@
+# SwiftUI Layout Best Practices Reference
+
+## Relative Layout Over Constants
+
+**Use dynamic layout calculations instead of hard-coded values.**
+
+```swift
+// Good - relative to actual layout
+GeometryReader { geometry in
+    VStack {
+        HeaderView()
+            .frame(height: geometry.size.height * 0.2)
+        ContentView()
+    }
+}
+
+// Avoid - magic numbers that don't adapt
+VStack {
+    HeaderView()
+        .frame(height: 150)  // Doesn't adapt to different screens
+    ContentView()
+}
+```
+
+**Why**: Hard-coded values don't account for different screen sizes, orientations, or dynamic content (like status bars during phone calls).
+
+## Context-Agnostic Views
+
+**Views should work in any context.** Never assume presentation style or screen size.
+
+```swift
+// Good - adapts to given space
+struct ProfileCard: View {
+    let user: User
+    
+    var body: some View {
+        VStack {
+            Image(user.avatar)
+                .resizable()
+                .aspectRatio(contentMode: .fit)
+            Text(user.name)
+            Spacer()
+        }
+        .padding()
+    }
+}
+
+// Avoid - assumes full screen
+struct ProfileCard: View {
+    let user: User
+    
+    var body: some View {
+        VStack {
+            Image(user.avatar)
+                .frame(width: UIScreen.main.bounds.width)  // Wrong!
+            Text(user.name)
+        }
+    }
+}
+```
+
+**Why**: Views should work as full screens, modals, sheets, popovers, or embedded content.
+
+## Own Your Container
+
+**Custom views should own static containers but not lazy/repeatable ones.**
+
+```swift
+// Good - owns static container
+struct HeaderView: View {
+    var body: some View {
+        HStack {
+            Image(systemName: "star")
+            Text("Title")
+            Spacer()
+        }
+    }
+}
+
+// Avoid - missing container
+struct HeaderView: View {
+    var body: some View {
+        Image(systemName: "star")
+        Text("Title")
+        // Caller must wrap in HStack
+    }
+}
+
+// Good - caller owns lazy container
+struct FeedView: View {
+    let items: [Item]
+    
+    var body: some View {
+        LazyVStack {
+            ForEach(items) { item in
+                ItemRow(item: item)
+            }
+        }
+    }
+}
+```
+
+## Layout Performance
+
+### Avoid Layout Thrash
+
+**Minimize deep view hierarchies and excessive layout dependencies.**
+
+```swift
+// Bad - deep nesting, excessive layout passes
+VStack {
+    HStack {
+        VStack {
+            HStack {
+                VStack {
+                    Text("Deep")
+                }
+            }
+        }
+    }
+}
+
+// Good - flatter hierarchy
+VStack {
+    Text("Shallow")
+    Text("Structure")
+}
+```
+
+**Avoid excessive `GeometryReader` and preference chains:**
+
+```swift
+// Bad - multiple geometry readers cause layout thrash
+GeometryReader { outerGeometry in
+    VStack {
+        GeometryReader { innerGeometry in
+            // Layout recalculates multiple times
+        }
+    }
+}
+
+// Good - single geometry reader or use alternatives (iOS 17+)
+containerRelativeFrame(.horizontal) { width, _ in
+    width * 0.8
+}
+```
+
+**Gate frequent geometry updates:**
+
+```swift
+// Bad - updates on every pixel change
+.onPreferenceChange(ViewSizeKey.self) { size in
+    currentSize = size
+}
+
+// Good - gate by threshold
+.onPreferenceChange(ViewSizeKey.self) { size in
+    let difference = abs(size.width - currentSize.width)
+    if difference > 10 {  // Only update if significant change
+        currentSize = size
+    }
+}
+```
+
+## View Logic and Testability
+
+### Separate View Logic from Views
+
+**Place view logic into view models or similar, so it can be tested.**
+
+> **iOS 17+**: Use `@Observable` macro with `@State` for view models.
+
+```swift
+// Good - logic in testable model (iOS 17+)
+@Observable
+@MainActor
+final class LoginViewModel {
+    var email = ""
+    var password = ""
+    var isValid: Bool {
+        !email.isEmpty && password.count >= 8
+    }
+
+    func login() async throws {
+        // Business logic here
+    }
+}
+
+struct LoginView: View {
+    @State private var viewModel = LoginViewModel()
+
+    var body: some View {
+        Form {
+            TextField("Email", text: $viewModel.email)
+            SecureField("Password", text: $viewModel.password)
+            Button("Login") {
+                Task {
+                    try? await viewModel.login()
+                }
+            }
+            .disabled(!viewModel.isValid)
+        }
+    }
+}
+```
+
+> **iOS 16 and earlier**: Use `ObservableObject` protocol with `@StateObject`.
+
+```swift
+// Good - logic in testable model (iOS 16 and earlier)
+@MainActor
+final class LoginViewModel: ObservableObject {
+    @Published var email = ""
+    @Published var password = ""
+    var isValid: Bool {
+        !email.isEmpty && password.count >= 8
+    }
+
+    func login() async throws {
+        // Business logic here
+    }
+}
+
+struct LoginView: View {
+    @StateObject private var viewModel = LoginViewModel()
+
+    var body: some View {
+        Form {
+            TextField("Email", text: $viewModel.email)
+            SecureField("Password", text: $viewModel.password)
+            Button("Login") {
+                Task {
+                    try? await viewModel.login()
+                }
+            }
+            .disabled(!viewModel.isValid)
+        }
+    }
+}
+```
+
+```swift
+// Bad - logic embedded in view
+struct LoginView: View {
+    @State private var email = ""
+    @State private var password = ""
+    
+    var body: some View {
+        Form {
+            TextField("Email", text: $email)
+            SecureField("Password", text: $password)
+            Button("Login") {
+                // Business logic directly in view - hard to test
+                Task {
+                    if !email.isEmpty && password.count >= 8 {
+                        // Login logic...
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+**Note**: This is about separating business logic for testability, not about enforcing specific architectures like MVVM. The goal is to make logic testable while keeping views simple.
+
+## Action Handlers
+
+**Separate layout from logic.** View body should reference action methods, not contain logic.
+
+```swift
+// Good - action references method
+struct PublishView: View {
+    @State private var viewModel = PublishViewModel()
+    
+    var body: some View {
+        Button("Publish Project", action: viewModel.handlePublish)
+    }
+}
+
+// Avoid - logic in closure
+struct PublishView: View {
+    @State private var isLoading = false
+    @State private var showError = false
+    
+    var body: some View {
+        Button("Publish Project") {
+            isLoading = true
+            apiService.publish(project) { result in
+                if case .error = result {
+                    showError = true
+                }
+                isLoading = false
+            }
+        }
+    }
+}
+```
+
+**Why**: Separating logic from layout improves readability, testability, and maintainability.
+
+## Summary Checklist
+
+- [ ] Use relative layout over hard-coded constants
+- [ ] Views work in any context (don't assume screen size)
+- [ ] Custom views own static containers
+- [ ] Avoid deep view hierarchies (layout thrash)
+- [ ] Gate frequent geometry updates by thresholds
+- [ ] View logic separated into testable models/classes
+- [ ] Action handlers reference methods, not inline logic
+- [ ] Avoid excessive `GeometryReader` usage
+- [ ] Use `containerRelativeFrame()` when appropriate