@mmerterden/multi-agent-pipeline 8.6.2 → 10.0.6

package/pipeline/skills/shared/external/swiftui-patterns/references/platform-and-sharing.md

@@ -40,7 +40,7 @@ extension UTType {
 }
 ```
 
-Representation order matters — place the most specific first, with broader fallbacks after.
+Representation order matters  -  place the most specific first, with broader fallbacks after.
 
 ### Built-in conformances
 
@@ -195,7 +195,7 @@ let data = try await note.exported(as: .note)
 UIPasteboard.general.setData(data, forPasteboardType: UTType.note.identifier)
 ```
 
-Prefer SwiftUI's `.copyable`, `.cuttable`, and `.pasteDestination` modifiers (iOS 16+) over direct `UIPasteboard` usage when possible — they integrate with the Edit menu and keyboard shortcuts automatically.
+Prefer SwiftUI's `.copyable`, `.cuttable`, and `.pasteDestination` modifiers (iOS 16+) over direct `UIPasteboard` usage when possible  -  they integrate with the Edit menu and keyboard shortcuts automatically.
 
 ### Common patterns
 
@@ -234,10 +234,10 @@ extension Report: Transferable {
 ### Pitfalls
 
 - Always declare custom `UTType` identifiers in Info.plist under Exported/Imported Type Identifiers.
-- Representation order matters — the first matching representation wins. Put the richest format first.
+- Representation order matters  -  the first matching representation wins. Put the richest format first.
 - `FileRepresentation` files are temporary; copy them if you need to persist.
 - `Transferable` conformance must be on the main type, not an extension in a different module, to avoid linker issues.
-- Test drag and drop on device — Simulator haptics and drop targeting differ from hardware.
+- Test drag and drop on device  -  Simulator haptics and drop targeting differ from hardware.
 
 ## Media Patterns
 
@@ -264,21 +264,23 @@ struct MediaPreviewRow: View {
     ScrollView(.horizontal, showsIndicators: false) {
       HStack {
         ForEach(attachments) { attachment in
-          LazyImage(url: attachment.previewURL) { state in
-            if let image = state.image {
-              image.resizable().aspectRatio(contentMode: .fill)
-            } else {
-              ProgressView()
-            }
-          }
-          .frame(width: 120, height: 120)
-          .clipped()
-          .onTapGesture {
+          Button {
             quickLook.prepareFor(
               selectedMediaAttachment: attachment,
               mediaAttachments: attachments
             )
+          } label: {
+            LazyImage(url: attachment.previewURL) { state in
+              if let image = state.image {
+                image.resizable().aspectRatio(contentMode: .fill)
+              } else {
+                ProgressView()
+              }
+            }
+            .frame(width: 120, height: 120)
+            .clipped()
           }
+          .buttonStyle(.plain)
         }
       }
     }
@@ -311,7 +313,7 @@ struct AppRoot: View {
 ### Pitfalls
 
 - Avoid loading full-size images in list rows; use resized previews.
-- Don’t present multiple viewer sheets at once; keep a single source of truth.
+- Don't present multiple viewer sheets at once; keep a single source of truth.
 
 ## Top Bar Overlays
 
@@ -343,7 +345,7 @@ content
   .safeAreaInset(edge: .top, spacing: 0) {
     VStack(spacing: 0) {
       TopSelectorView()
-        .padding(.vertical, 8)
+        .padding(.vertical)
         .padding(.horizontal, .layoutPadding)
         .background(Color.primary.opacity(0.06))
         .background(Material.ultraThin)
@@ -360,7 +362,7 @@ content
 
 ### Pitfalls
 
-- Don’t stack multiple top insets; it can create extra padding.
+- Don't stack multiple top insets; it can create extra padding.
 - Avoid heavy, opaque backgrounds that fight the navigation bar.
 
 ## Title Menus
@@ -454,7 +456,7 @@ ToolbarItem(placement: .principal) {
 
 ### Pitfalls
 
-- Don’t overload the menu with too many options.
+- Don't overload the menu with too many options.
 - Avoid using title menus for destructive actions.
 
 ## Input Toolbar
@@ -476,24 +478,26 @@ Use a bottom-anchored input bar for chat, composer, or quick actions without fig
 @MainActor
 struct ConversationView: View {
   @FocusState private var isInputFocused: Bool
+  @State private var scrollPosition = ScrollPosition(edge: .bottom)
+  @State private var draft = ""
 
   var body: some View {
-    ScrollViewReader { _ in
-      ScrollView {
-        LazyVStack {
-          ForEach(messages) { message in
-            MessageRow(message: message)
-          }
+    ScrollView {
+      LazyVStack {
+        ForEach(messages) { message in
+          MessageRow(message: message)
         }
-        .padding(.horizontal, .layoutPadding)
-      }
-      .safeAreaInset(edge: .bottom) {
-        InputBar(text: $draft)
-          .focused($isInputFocused)
       }
-      .scrollDismissesKeyboard(.interactively)
-      .onAppear { isInputFocused = true }
+      .scrollTargetLayout()
+      .padding(.horizontal, .layoutPadding)
+    }
+    .scrollPosition($scrollPosition)
+    .safeAreaInset(edge: .bottom) {
+      InputBar(text: $draft)
+        .focused($isInputFocused)
     }
+    .scrollDismissesKeyboard(.interactively)
+    .onAppear { isInputFocused = true }
   }
 }
 ```
@@ -619,7 +623,7 @@ struct ItemCommands: Commands {
 ### Pitfalls
 
 - Avoid registering the same keyboard shortcut in multiple command groups.
-- Don’t use menu items as the only discoverable entry point for critical features.
+- Don't use menu items as the only discoverable entry point for critical features.
 
 ## macOS Settings
 
@@ -692,5 +696,5 @@ struct SettingsView: View {
 
 ### Pitfalls
 
-- Don’t reuse iOS-only settings layouts (full-screen stacks, toolbar-heavy flows).
+- Don't reuse iOS-only settings layouts (full-screen stacks, toolbar-heavy flows).
 - Avoid large custom view hierarchies inside `Form`; keep rows focused and accessible.

package/pipeline/skills/shared/external/swiftui-performance/SKILL.md

@@ -5,9 +5,10 @@ description: "Audit and improve SwiftUI runtime performance. Use when diagnosing
 
 # SwiftUI Performance
 
+Audit SwiftUI view performance end-to-end, from instrumentation and baselining to root-cause analysis and concrete remediation steps.
+
 ## Contents
 
-- [Overview](#overview)
 - [Workflow Decision Tree](#workflow-decision-tree)
 - [1. Code-First Review](#1-code-first-review)
 - [2. Guide the User to Profile](#2-guide-the-user-to-profile)
@@ -24,10 +25,6 @@ description: "Audit and improve SwiftUI runtime performance. Use when diagnosing
 - [Review Checklist](#review-checklist)
 - [References](#references)
 
-## Overview
-
-Audit SwiftUI view performance end-to-end, from instrumentation and baselining to root-cause analysis and concrete remediation steps.
-
 ## Workflow Decision Tree
 
 - If the user provides code, start with "Code-First Review."
@@ -200,53 +197,20 @@ Provide:
 
 ## Instruments Profiling
 
-### SwiftUI Instrument Template
-
-Instruments ships with a dedicated **SwiftUI** template (available in Xcode 15+ / Instruments 15+). This template provides:
-
-- **SwiftUI View Body** instrument -- counts how many times each view's `body` is evaluated.
-- **SwiftUI View Properties** instrument -- tracks `@State`, `@Binding`, and `@Observable` property changes that trigger view updates.
-- **Time Profiler** -- standard CPU profiler for identifying expensive `body` computations.
-- **Hangs** instrument -- flags main-thread hangs > 250ms.
+Use the **SwiftUI instrument template** in Xcode (Cmd+I to profile). Key instruments: SwiftUI View Body (body evaluation counts), SwiftUI View Properties (state change tracking), Time Profiler, and Hangs.
 
-### Profiling Workflow
-
-1. **Build for Profiling.** Product > Profile (Cmd+I) in Xcode. This creates a Release build with profiling symbols.
-2. **Select the SwiftUI template.** Or create a custom template with SwiftUI + Time Profiler + Hangs.
-3. **Record the interaction.** Reproduce the exact scroll, navigation, or animation that is slow.
-4. **Inspect the SwiftUI lane.** Look for views with high body evaluation counts. A view evaluated hundreds of times during a single scroll is likely the bottleneck.
-5. **Cross-reference with Time Profiler.** If a view body is called often AND takes significant time per call, that is the priority fix.
-
-### View Body Evaluation Count
-
-In the SwiftUI instrument lane, each row represents a view type. Key signals:
-
-- **High count, low time per call:** Identity or state-invalidation problem (too many re-evaluations).
-- **Low count, high time per call:** Expensive computation inside `body` (formatting, sorting, image work).
-- **High count AND high time:** Both problems -- fix the expensive work first, then fix the invalidation.
-
-### Identifying Unnecessary Redraws
-
-Add `Self._printChanges()` in Debug builds to log exactly which property triggered a view update:
+Add `Self._printChanges()` in debug builds to log which property triggered a view update:
 
 ```swift
 var body: some View {
     #if DEBUG
-    let _ = Self._printChanges()  // prints: "MyView: @self, _count changed."
+    let _ = Self._printChanges()  // "MyView: @self, _count changed."
     #endif
     Text("Count: \(count)")
 }
 ```
 
-Remove `_printChanges()` before submitting to the App Store -- it is a debug-only API.
-
-### Time Profiler for Body Hotspots
-
-When Time Profiler shows significant time in a view's `body`:
-
-1. Filter the call tree by the view type name.
-2. Look for allocations (`NumberFormatter()`, `DateFormatter()`), collection operations (`.sorted()`, `.filter()`), or image decoding.
-3. Move expensive operations to `onChange`, `task`, or precomputed `@State`.
+See [references/optimizing-swiftui-performance-instruments.md](references/optimizing-swiftui-performance-instruments.md) for the full profiling workflow.
 
 ## Identity and Lifetime
 
@@ -303,6 +267,29 @@ func makeView(for item: Item) -> some View {
 
 `AnyView` also prevents SwiftUI from detecting which branch changed, causing full subtree replacement instead of targeted updates.
 
+### Ternary Modifiers Preserve Structural Identity
+
+`if`/`else` in a view builder creates `_ConditionalContent`  -  two separate view branches with distinct identities. When the condition changes, SwiftUI destroys one branch and creates the other, resetting all `@State`.
+
+For toggling **modifiers** on the same view, use a ternary expression instead:
+
+```swift
+// DON'T: if/else creates two separate Text views with different identities
+if isHighlighted {
+    Text(title).foregroundStyle(.yellow)
+} else {
+    Text(title).foregroundStyle(.primary)
+}
+
+// DO: ternary keeps one Text view, just changes the modifier value
+Text(title)
+    .foregroundStyle(isHighlighted ? .yellow : .primary)
+```
+
+This preserves the view's identity (and its state) across the condition change, and SwiftUI can animate the transition smoothly.
+
+Use `if`/`else` when the **view type itself** differs between branches. Use ternary when only a **property or modifier** changes.
+
 ### id() Modifier Impacts
 
 The `.id()` modifier assigns explicit identity. Changing the value **destroys and recreates** the view:
@@ -335,7 +322,7 @@ Lazy stacks only create views for items currently visible on screen. Off-screen
 
 ```swift
 ScrollView {
-    LazyVStack(spacing: 12) {
+    LazyVStack {
         ForEach(items) { item in
             ItemRow(item: item)
         }
@@ -357,7 +344,7 @@ Use lazy grids for multi-column layouts:
 let columns = [GridItem(.adaptive(minimum: 150))]
 
 ScrollView {
-    LazyVGrid(columns: columns, spacing: 16) {
+    LazyVGrid(columns: columns) {
         ForEach(photos) { photo in
             PhotoThumbnail(photo: photo)
         }
@@ -382,11 +369,11 @@ let fixedColumns = [
 | Always-visible content | `VStack` (no benefit to lazy) |
 | Scrollable lists | `LazyVStack` inside `ScrollView`, or `List` |
 
-**Important:** Do not nest `GeometryReader` inside lazy containers. It forces eager measurement and defeats lazy loading. Use `.onGeometryChange` (iOS 18+) instead.
+**Important:** Do not nest `GeometryReader` inside lazy containers. It forces eager measurement and defeats lazy loading. Use `.onGeometryChange` (iOS 16+) instead.
 
 ## State and Observation Optimization
 
-### @Observable Granular Tracking
+### `@Observable` Granular Tracking
 
 `@Observable` (Observation framework, iOS 17+) tracks property access at the **per-property level**. A view only re-evaluates when properties it actually read in `body` change:
 
@@ -460,7 +447,7 @@ Use computed properties on `@Observable` models to derive state without introduc
 
 1. **Profiling Debug builds.** Debug builds include extra runtime checks and disable optimizations, producing misleading perf data. Profile Release builds on a real device.
 2. **Observing an entire model when only one property is needed.** Break large `@Observable` models into focused ones, or use computed properties/closures to narrow observation scope.
-3. **Using `GeometryReader` inside ScrollView items.** GeometryReader forces eager sizing and defeats lazy loading. Prefer `.onGeometryChange` (iOS 18+) or measure outside the lazy container.
+3. **Using `GeometryReader` inside ScrollView items.** GeometryReader forces eager sizing and defeats lazy loading. Prefer `.onGeometryChange` (iOS 16+) or measure outside the lazy container.
 4. **Calling `DateFormatter()` or `NumberFormatter()` inside `body`.** These are expensive to create. Make them static or move them outside the view.
 5. **Animating non-equatable state.** If SwiftUI cannot determine equality, it redraws every frame. Conform state to `Equatable`, then use `.animation(_:value:)` for simple value-bound changes or `.animation(_:body:)` for narrower modifier-scoped implicit animation.
 6. **Large flat `List` without identifiers.** Use `id:` or make items `Identifiable` so SwiftUI can diff efficiently instead of rebuilding the entire list.
@@ -481,7 +468,8 @@ Use computed properties on `@Observable` models to derive state without introduc
 
 ## References
 
-- Demystify SwiftUI performance (WWDC23): `references/demystify-swiftui-performance-wwdc23.md`
-- Optimizing SwiftUI performance with Instruments: `references/optimizing-swiftui-performance-instruments.md`
-- Understanding hangs in your app: `references/understanding-hangs-in-your-app.md`
-- Understanding and improving SwiftUI performance: `references/understanding-improving-swiftui-performance.md`
+- Demystify SwiftUI performance (WWDC23): [references/demystify-swiftui-performance-wwdc23.md](references/demystify-swiftui-performance-wwdc23.md)
+- Optimizing SwiftUI performance with Instruments: [references/optimizing-swiftui-performance-instruments.md](references/optimizing-swiftui-performance-instruments.md)
+- Understanding hangs in your app: [references/understanding-hangs-in-your-app.md](references/understanding-hangs-in-your-app.md)
+- Understanding and improving SwiftUI performance: [references/understanding-improving-swiftui-performance.md](references/understanding-improving-swiftui-performance.md)
+- WWDC transcript sources: [references/wwdc-session-sources.md](references/wwdc-session-sources.md)

package/pipeline/skills/shared/external/swiftui-performance/references/demystify-swiftui-performance-wwdc23.md

@@ -1,46 +1,220 @@
 # Demystify SwiftUI Performance (WWDC23) (Summary)
 
-Context: WWDC23 session on building a mental model for SwiftUI performance and triaging hangs/hitches.
+Context: WWDC23 session on building a mental model for SwiftUI performance and
+triaging hangs, hitches, and excessive update work.
 
-## Performance loop
+## Contents
+- Core mental model
+- Dependencies and invalidation
+- Expensive body work
+- Identity rules for lists and tables
+- Initialization and lifecycle pitfalls
+- Debugging tools
+- Fix patterns
+- What to verify after a change
 
-- Measure -> Identify -> Optimize -> Re-measure.
-- Focus on concrete symptoms (slow navigation, broken animations, spinning cursor).
+## Core mental model
 
-## Dependencies and updates
+SwiftUI performance starts with one rule: only work that is required for the
+current state should happen for the current frame.
 
-- Views form a dependency graph; dynamic properties are a frequent source of updates.
-- Use `Self._printChanges()` in debug only to inspect extra dependencies.
-- Eliminate unnecessary dependencies by extracting views or narrowing state.
-- Consider `@Observable` for more granular property tracking.
+A slow screen usually means one of these is false:
 
-## Common causes of slow updates
+- too much work happens per update
+- updates happen too often
+- identity is unstable, so SwiftUI redoes work it could have reused
 
-- Expensive view bodies (string interpolation, filtering, formatting).
-- Dynamic property instantiation and state initialization in `body`.
-- Slow identity resolution in lists/tables.
-- Hidden work: bundle lookups, heap allocations, repeated string construction.
+The session's practical loop is:
 
-## Avoid slow initialization in view bodies
+- Measure
+- Identify
+- Optimize
+- Re-measure
 
-- Don't create heavy models synchronously in view bodies.
-- Use `.task` to fetch async data and keep `init` lightweight.
+Do not skip the last step. SwiftUI optimizations are easy to misjudge by eye.
 
-## Lists and tables identity rules
+## Dependencies and invalidation
 
-- Stable identity is critical for performance and animation.
-- Ensure a constant number of views per element in `ForEach`.
-- Avoid inline filtering in `ForEach`; pre-filter and cache collections.
-- Avoid `AnyView` in list rows; it hides identity and increases cost.
-- Flatten nested `ForEach` when possible to reduce overhead.
+A view updates when one of its dependencies changes.
 
-## Table specifics
+Common dependency sources:
 
-- `TableRow` resolves to a single row; row count must be constant.
-- Prefer the streamlined `Table` initializer to enforce constant rows.
-- Use explicit IDs for back deployment when needed.
+- `@State`
+- `@Binding`
+- `@Observable` / `@ObservedObject`
+- `@Environment`
+- container-derived identity (`ForEach`, `List`, `Table`)
 
-## Debugging aids
+The performance goal is not "fewer dependencies" in the abstract. The goal is
+**precise dependencies** so only the view that needs to update actually updates.
 
-- Use Instruments for hangs and hitches.
-- Use `_printChanges` to validate dependency assumptions during debug.
+### Practical implications
+
+- Avoid a row depending on a whole collection if it only needs one element.
+- Avoid broad environment-driven updates for fast-changing values.
+- Extract subviews when a smaller view can read a smaller state surface.
+
+### Debug-only dependency inspection
+
+`Self._printChanges()` is useful in debug builds when you are not sure why a
+view keeps updating.
+
+Use it to answer:
+
+- which property changed?
+- which parent view re-rendered?
+- is the view reacting to state it should not care about?
+
+Do not treat `_printChanges()` output as a shipping-time profiling tool.
+
+## Expensive body work
+
+View bodies need to stay cheap.
+
+Typical mistakes:
+
+- string formatting in `body`
+- array filtering and sorting in `body`
+- expensive image work in `body`
+- constructing large attributed strings during render
+- initializing heavy models in-line with view creation
+
+```swift
+// DON'T
+var body: some View {
+    List(items.filter(shouldShow).sorted(by: sortRule)) { item in
+        Text(numberFormatter.string(from: item.value as NSNumber) ?? "")
+    }
+}
+
+// DO
+var body: some View {
+    List(viewModel.visibleItems) { item in
+        Text(item.formattedValue)
+    }
+}
+```
+
+The winning pattern is precomputation at the model boundary, not clever work in
+`body`.
+
+## Identity rules for lists and tables
+
+Identity is one of the biggest hidden performance levers in SwiftUI.
+
+### Stable identity matters
+
+Use stable IDs that survive refreshes and sorting. If identity churns, SwiftUI
+cannot reuse rows, preserve animations, or diff efficiently.
+
+### Constant row count matters
+
+Inside `ForEach`, SwiftUI expects a predictable mapping between data elements and
+rendered views.
+
+Avoid patterns like:
+
+```swift
+ForEach(items) { item in
+    if item.isVisible {
+        Row(item: item)
+    }
+}
+```
+
+Prefer:
+
+```swift
+ForEach(visibleItems) { item in
+    Row(item: item)
+}
+```
+
+### Avoid `AnyView` in hot list rows
+
+Type erasure can hide useful structural information and increase work in large
+lists or tables.
+
+### Table-specific note
+
+`TableRow` resolves to a single row. Keep row structure predictable and use the
+streamlined `Table` APIs when possible.
+
+## Initialization and lifecycle pitfalls
+
+### Heavy model creation in view init/body
+
+Keep view initialization lightweight. Start async work with `.task` or from a
+model object.
+
+```swift
+// DON'T
+struct DetailView: View {
+    let loader = BigLoader() // heavy construction
+}
+
+// DO
+struct DetailView: View {
+    @State private var model: DetailModel?
+
+    var body: some View {
+        content
+            .task {
+                model = await loadDetailModel()
+            }
+    }
+}
+```
+
+### Hidden work from computed properties
+
+A computed property can still be body work if it runs during render. If it is
+expensive, treat it like body work and precompute it.
+
+## Debugging tools
+
+### Instruments
+
+Use Instruments for hangs, hitches, update counts, and expensive frames.
+
+### `_printChanges()`
+
+Use it in debug to inspect dependency behavior.
+
+### Release-build validation
+
+A debug build can make SwiftUI performance look worse or different than a
+shipping build. Validate important performance changes in Release on device.
+
+## Fix patterns
+
+### Split views by dependency boundary
+
+If one small piece of state changes frequently, isolate the subview that reads
+it.
+
+### Pre-filter and cache collections
+
+Do filtering, mapping, sorting, and grouping before rendering.
+
+### Avoid broad environment reads in hot paths
+
+Environment is convenient but not free. Keep fast-changing values local unless
+multiple subtrees truly need them.
+
+### Reduce hidden allocations
+
+Move formatters, bundle lookups, and derived strings out of repeated body paths.
+
+## What to verify after a change
+
+After optimizing, check all of the following:
+
+- the target interaction feels smoother
+- update counts dropped in Instruments
+- row identity stayed stable across reloads
+- animation behavior still matches product intent
+- no correctness bugs were introduced by caching or splitting views
+
+A performance fix that breaks state ownership or animation correctness is not a
+real fix.