/apple-engineer-superpowers

name: apple-engineer-superpowers
description: Use when writing Swift code for Apple platforms - iOS, macOS, visionOS. Covers Swift 6 concurrency, actors, Sendable, async/await, SwiftUI, MVVM architecture, Metal GPU programming, RealityKit ECS, visionOS scenes, interpolation/animation, advanced collection types, property wrappers, Combine bridging, error handling, testing, and API design patterns.

Apple Platform Engineering

Comprehensive Swift engineering standards for building production-quality Apple platform applications.

Core Principles

1. **No Force Unwrapping (`!`)** - Use `guard let`, `if let`, nil coalescing (`??`), or optional chaining. Never crash on nil. 2. **Actor-First Concurrency** - Use actors as the default for stateful components. Prefer actor isolation over manual locking. 3. **Async/Await Always** - Never use completion handlers in new code. Use `async throws` functions. 4. **Sendable Everything** - All shared types must conform to `Sendable`. All closures crossing concurrency boundaries must be `@Sendable`. 5. **Swift 6 Strict Concurrency** - Enable `StrictConcurrency` from the start. No data races. 6. **Protocol-Oriented Design** - Define contracts through protocols. Use dependency injection for testability. 7. **LocalizedError for Errors** - Domain-specific error enums conforming to `LocalizedError, Sendable`.

Quick Reference

Safe Optional Handling

| Instead of | Use | |------------|-----| | `value!` | `guard let value else { return }` | | `string.data(using: .utf8)!` | `string.data(using: .utf8) ?? Data()` | | `url!` | `guard let url = URL(string: s) else { return }` | | `object.property!` | `object.property?.method()` or `if let prop = object.property { }` |

Concurrency Primitives

| Need | Use | |------|-----| | Stateful shared component | `actor` | | Simple value protection | `Mutex<State>` | | Low-level sync | `OSAllocatedUnfairLock` | | UI state management | `@MainActor` on ViewModels | | Progress/events stream | `AsyncStream` / `AsyncThrowingStream` | | Multi-subscriber broadcast | `AsyncBroadcastChannel` or `AsyncNotifier` |

Actor vs @MainActor Decision

| Scenario | Use | |----------|-----| | API service, data operations | `actor` | | ViewModel with `@Published` | `@MainActor final class: ObservableObject` | | Service with `@Published` properties Views observe | `@MainActor ObservableObject` (rare) | | Pure data model | `struct: Sendable` |

Error Handling Pattern

enum ServiceError: LocalizedError, Sendable {
    case operationFailed(String)

    var errorDescription: String? {
        switch self {
        case .operationFailed(let msg): return "Operation failed: \(msg)"
        }
    }
}

API Design

| Pattern | Use | |---------|-----| | `func work() async throws -> T` | Standard async operation | | `func work() -> AsyncThrowingStream<Event, Error>` | Progress/event reporting | | `func work(progress: @Sendable (Float) -> Void) async throws -> T` | Simple progress callback |

Metal GPU Quick Reference

| Need | Use | |------|-----| | Compute pipeline | `MTLComputePipelineDescriptor` + `device.makeComputePipelineState` | | Render pipeline | `MTLRenderPipelineDescriptor` + vertex/fragment functions | | Buffer management | `MetalBuffer<Element>` generic wrapper | | Multi-frame pipelining | Ring buffer (pool of 3) with `tick()` | | Texture from IOSurface | `device.makeTexture(descriptor:iosurface:plane:)` | | Threadgroup sizing | `min(elementCount, pipelineState.maxTotalThreadsPerThreadgroup)` |

RealityKit/visionOS Quick Reference

| Need | Use | |------|-----| | Custom entity data | `struct: Component` | | Per-frame logic | `class: System` with scene subscriptions | | Show entities in SwiftUI | `RealityView { content in content.add(entity) }` | | Observe component changes | `entity.componentChangePublisher(T.self)` | | Full immersion | `ImmersiveSpace(id:) { }.immersionStyle(.full)` | | Multi-window | `WindowGroup(id:)` with `WindowPlacement` |

Advanced Patterns Quick Reference

| Need | Use | |------|-----| | Smooth value tracking | `ExponentialDamper<T: Lerpable>` | | Generic interpolation | `Lerpable` protocol with `lerp(from:to:blend:)` | | Non-empty guarantee | `NonEmpty<C: Collection>` | | Enum-keyed storage | `Table<E: CaseIterable, V>` | | Multi-consumer async | `AsyncBroadcastChannel` with back-pressure | | Combine to async | `publisher.sinkSingleValue() async throws` | | Custom defaults | `@DefaultValue<T>` property wrapper |

Detailed References

• **swift-concurrency.md** — Swift 6 concurrency patterns: actors, Sendable, AsyncSequence, task cancellation, synchronization, state machines, reactive patterns, generics, persistence, networking, testing, diagnostics
• **swiftui-architecture.md** — SwiftUI app architecture: MVVM, ViewModel/View guidelines, service layer patterns, data flow, App Intents, file organization
• **metal-graphics.md** — Metal GPU programming: pipelines, buffers, textures, compute dispatch, ring buffers, shaders, frame pacing
• **realitykit-visionos.md** — RealityKit ECS and visionOS: entities, components, systems, scene subscriptions, immersive spaces, windows, hand tracking
• **advanced-swift-patterns.md** — Property wrappers, interpolation/animation, collection types, Combine bridging, advanced async abstractions, @dynamicMemberLookup