1---2name: apple-engineer-superpowers3description: 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.4---56# Apple Platform Engineering78Comprehensive Swift engineering standards for building production-quality Apple platform applications.910## Core Principles11121. **No Force Unwrapping (`!`)** - Use `guard let`, `if let`, nil coalescing (`??`), or optional chaining. Never crash on nil.132. **Actor-First Concurrency** - Use actors as the default for stateful components. Prefer actor isolation over manual locking.143. **Async/Await Always** - Never use completion handlers in new code. Use `async throws` functions.154. **Sendable Everything** - All shared types must conform to `Sendable`. All closures crossing concurrency boundaries must be `@Sendable`.165. **Swift 6 Strict Concurrency** - Enable `StrictConcurrency` from the start. No data races.176. **Protocol-Oriented Design** - Define contracts through protocols. Use dependency injection for testability.187. **LocalizedError for Errors** - Domain-specific error enums conforming to `LocalizedError, Sendable`.1920## Quick Reference2122### Safe Optional Handling2324| Instead of | Use |25|------------|-----|26| `value!` | `guard let value else { return }` |27| `string.data(using: .utf8)!` | `string.data(using: .utf8) ?? Data()` |28| `url!` | `guard let url = URL(string: s) else { return }` |29| `object.property!` | `object.property?.method()` or `if let prop = object.property { }` |3031### Concurrency Primitives3233| Need | Use |34|------|-----|35| Stateful shared component | `actor` |36| Simple value protection | `Mutex<State>` |37| Low-level sync | `OSAllocatedUnfairLock` |38| UI state management | `@MainActor` on ViewModels |39| Progress/events stream | `AsyncStream` / `AsyncThrowingStream` |40| Multi-subscriber broadcast | `AsyncBroadcastChannel` or `AsyncNotifier` |4142### Actor vs @MainActor Decision4344| Scenario | Use |45|----------|-----|46| API service, data operations | `actor` |47| ViewModel with `@Published` | `@MainActor final class: ObservableObject` |48| Service with `@Published` properties Views observe | `@MainActor ObservableObject` (rare) |49| Pure data model | `struct: Sendable` |5051### Error Handling Pattern5253```swift54enum ServiceError: LocalizedError, Sendable {55 case operationFailed(String)5657 var errorDescription: String? {58 switch self {59 case .operationFailed(let msg): return "Operation failed: \(msg)"60 }61 }62}63```6465### API Design6667| Pattern | Use |68|---------|-----|69| `func work() async throws -> T` | Standard async operation |70| `func work() -> AsyncThrowingStream<Event, Error>` | Progress/event reporting |71| `func work(progress: @Sendable (Float) -> Void) async throws -> T` | Simple progress callback |7273### Metal GPU Quick Reference7475| Need | Use |76|------|-----|77| Compute pipeline | `MTLComputePipelineDescriptor` + `device.makeComputePipelineState` |78| Render pipeline | `MTLRenderPipelineDescriptor` + vertex/fragment functions |79| Buffer management | `MetalBuffer<Element>` generic wrapper |80| Multi-frame pipelining | Ring buffer (pool of 3) with `tick()` |81| Texture from IOSurface | `device.makeTexture(descriptor:iosurface:plane:)` |82| Threadgroup sizing | `min(elementCount, pipelineState.maxTotalThreadsPerThreadgroup)` |8384### RealityKit/visionOS Quick Reference8586| Need | Use |87|------|-----|88| Custom entity data | `struct: Component` |89| Per-frame logic | `class: System` with scene subscriptions |90| Show entities in SwiftUI | `RealityView { content in content.add(entity) }` |91| Observe component changes | `entity.componentChangePublisher(T.self)` |92| Full immersion | `ImmersiveSpace(id:) { }.immersionStyle(.full)` |93| Multi-window | `WindowGroup(id:)` with `WindowPlacement` |9495### Advanced Patterns Quick Reference9697| Need | Use |98|------|-----|99| Smooth value tracking | `ExponentialDamper<T: Lerpable>` |100| Generic interpolation | `Lerpable` protocol with `lerp(from:to:blend:)` |101| Non-empty guarantee | `NonEmpty<C: Collection>` |102| Enum-keyed storage | `Table<E: CaseIterable, V>` |103| Multi-consumer async | `AsyncBroadcastChannel` with back-pressure |104| Combine to async | `publisher.sinkSingleValue() async throws` |105| Custom defaults | `@DefaultValue<T>` property wrapper |106107## Detailed References108109- **swift-concurrency.md** — Swift 6 concurrency patterns: actors, Sendable, AsyncSequence, task cancellation, synchronization, state machines, reactive patterns, generics, persistence, networking, testing, diagnostics110- **swiftui-architecture.md** — SwiftUI app architecture: MVVM, ViewModel/View guidelines, service layer patterns, data flow, App Intents, file organization111- **metal-graphics.md** — Metal GPU programming: pipelines, buffers, textures, compute dispatch, ring buffers, shaders, frame pacing112- **realitykit-visionos.md** — RealityKit ECS and visionOS: entities, components, systems, scene subscriptions, immersive spaces, windows, hand tracking113- **advanced-swift-patterns.md** — Property wrappers, interpolation/animation, collection types, Combine bridging, advanced async abstractions, @dynamicMemberLookup
piemonte