opencode-skills-antigravity 1.0.12 → 1.0.14

package/bundled-skills/swiftui-performance-audit/references/demystify-swiftui-performance-wwdc23.md

@@ -0,0 +1,46 @@
+# Demystify SwiftUI Performance (WWDC23) (Summary)
+
+Context: WWDC23 session on building a mental model for SwiftUI performance and triaging hangs/hitches.
+
+## Performance loop
+
+- Measure -> Identify -> Optimize -> Re-measure.
+- Focus on concrete symptoms (slow navigation, broken animations, spinning cursor).
+
+## Dependencies and updates
+
+- 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.
+
+## Common causes of slow updates
+
+- 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.
+
+## Avoid slow initialization in view bodies
+
+- Don’t create heavy models synchronously in view bodies.
+- Use `.task` to fetch async data and keep `init` lightweight.
+
+## Lists and tables identity rules
+
+- 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.
+
+## Table specifics
+
+- `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.
+
+## Debugging aids
+
+- Use Instruments for hangs and hitches.
+- Use `_printChanges` to validate dependency assumptions during debug.

package/bundled-skills/swiftui-performance-audit/references/optimizing-swiftui-performance-instruments.md

@@ -0,0 +1,29 @@
+# Optimizing SwiftUI Performance with Instruments (Summary)
+
+Context: WWDC session introducing the next-generation SwiftUI Instrument in Instruments 26 and how to diagnose SwiftUI-specific bottlenecks.
+
+## Key takeaways
+
+- Profile SwiftUI issues with the SwiftUI template (SwiftUI instrument + Time Profiler + Hangs/Hitches).
+- Long view body updates are a common bottleneck; use "Long View Body Updates" to identify slow bodies.
+- Set inspection range on a long update and correlate with Time Profiler to find expensive frames.
+- Keep work out of `body`: move formatting, sorting, image decoding, and other expensive work into cached or precomputed paths.
+- Use Cause & Effect Graph to diagnose *why* updates occur; SwiftUI is declarative, so backtraces are often unhelpful.
+- Avoid broad dependencies that trigger many updates (e.g., `@Observable` arrays or global environment reads).
+- Prefer granular view models and scoped state so only the affected view updates.
+- Environment values update checks still cost time; avoid placing fast-changing values (timers, geometry) in environment.
+- Profile early and often during feature development to catch regressions.
+
+## Suggested workflow (condensed)
+
+1. Record a trace in Release mode using the SwiftUI template.
+2. Inspect "Long View Body Updates" and "Other Long Updates."
+3. Zoom into a long update, then inspect Time Profiler for hot frames.
+4. Fix slow body work by moving heavy logic into precomputed/cache paths.
+5. Use Cause & Effect Graph to identify unintended update fan-out.
+6. Re-record and compare the update counts and hitch frequency.
+
+## Example patterns from the session
+
+- Caching formatted distance strings in a location manager instead of computing in `body`.
+- Replacing a dependency on a global favorites array with per-item view models to reduce update fan-out.

package/bundled-skills/swiftui-performance-audit/references/profiling-intake.md

@@ -0,0 +1,44 @@
+# Profiling intake and collection checklist
+
+## Intent
+
+Use this checklist when code review alone cannot explain the SwiftUI performance issue and you need runtime evidence from the user.
+
+## Ask for first
+
+- Exact symptom: CPU spike, dropped frames, memory growth, hangs, or excessive view updates.
+- Exact interaction: scrolling, typing, initial load, navigation push/pop, animation, sheet presentation, or background refresh.
+- Target device and OS version.
+- Whether the issue was reproduced on a real device or only in Simulator.
+- Build configuration: Debug or Release.
+- Whether the user already has a baseline or before/after comparison.
+
+## Default profiling request
+
+Ask the user to:
+- Run the app in a Release build when possible.
+- Use the SwiftUI Instruments template.
+- Reproduce the exact problematic interaction only long enough to capture the issue.
+- Capture the SwiftUI timeline and Time Profiler together.
+- Export the trace or provide screenshots of the key SwiftUI lanes and the Time Profiler call tree.
+
+## Ask for these artifacts
+
+- Trace export or screenshots of the relevant SwiftUI lanes
+- Time Profiler call tree screenshot or export
+- Device/OS/build configuration
+- A short note describing what action was happening at the time of the capture
+- If memory is involved, the memory graph or Allocations data if available
+
+## When to ask for more
+
+- Ask for a second capture if the first run mixes multiple interactions.
+- Ask for a before/after pair if the user has already tried a fix.
+- Ask for a device capture if the issue only appears in Simulator or if scrolling smoothness matters.
+
+## Common traps
+
+- Debug builds can distort SwiftUI timing and allocation behavior.
+- Simulator traces can miss device-only rendering or memory issues.
+- Mixed interactions in one capture make attribution harder.
+- Screenshots without the reproduction note are much harder to interpret.

package/bundled-skills/swiftui-performance-audit/references/report-template.md

@@ -0,0 +1,47 @@
+# Audit output template
+
+## Intent
+
+Use this structure when reporting SwiftUI performance findings so the user can quickly see the symptom, evidence, likely cause, and next validation step.
+
+## Template
+
+```markdown
+## Summary
+
+[One short paragraph on the most likely bottleneck and whether the conclusion is code-backed or trace-backed.]
+
+## Findings
+
+1. [Issue title]
+   - Symptom: [what the user sees]
+   - Likely cause: [root cause]
+   - Evidence: [code reference or profiling evidence]
+   - Fix: [specific change]
+   - Validation: [what to measure after the fix]
+
+2. [Issue title]
+   - Symptom: ...
+   - Likely cause: ...
+   - Evidence: ...
+   - Fix: ...
+   - Validation: ...
+
+## Metrics
+
+| Metric | Before | After | Notes |
+| --- | --- | --- | --- |
+| CPU | [value] | [value] | [note] |
+| Frame drops / hitching | [value] | [value] | [note] |
+| Memory peak | [value] | [value] | [note] |
+
+## Next step
+
+[One concrete next action: apply a fix, capture a better trace, or validate on device.]
+```
+
+## Notes
+
+- Order findings by impact, not by file order.
+- Say explicitly when a conclusion is still a hypothesis.
+- If no metrics are available, omit the table and say what should be measured next.

package/bundled-skills/swiftui-performance-audit/references/understanding-hangs-in-your-app.md

@@ -0,0 +1,33 @@
+# Understanding Hangs in Your App (Summary)
+
+Context: Apple guidance on identifying hangs caused by long-running main-thread work and understanding the main run loop.
+
+## Key concepts
+
+- A hang is a noticeable delay in a discrete interaction (typically >100 ms).
+- Hangs almost always come from long-running work on the main thread.
+- The main run loop processes UI events, timers, and main-queue work sequentially.
+
+## Main-thread work stages
+
+- Event delivery to the correct view/handler.
+- Your code: state updates, data fetch, UI changes.
+- Core Animation commit to the render server.
+
+## Why the main run loop matters
+
+- Only the main thread can update UI safely.
+- The run loop is the foundation that executes main-queue work.
+- If the run loop is busy, it can’t handle new events; this causes hangs.
+
+## Diagnosing hangs
+
+- Observe the main run loop’s busy periods: healthy loops sleep most of the time.
+- Hang detection typically flags busy periods >250 ms.
+- The Hangs instrument can be configured to lower thresholds.
+
+## Practical takeaways
+
+- Keep main-thread work short; offload heavy work from event handlers.
+- Avoid long-running tasks on the main dispatch queue or main actor.
+- Use run loop behavior as a proxy for user-perceived responsiveness.

package/bundled-skills/swiftui-performance-audit/references/understanding-improving-swiftui-performance.md

@@ -0,0 +1,52 @@
+# Understanding and Improving SwiftUI Performance (Summary)
+
+Context: Apple guidance on diagnosing SwiftUI performance with Instruments and applying design patterns to reduce long or frequent updates.
+
+## Core concepts
+
+- SwiftUI is declarative; view updates are driven by state, environment, and observable data dependencies.
+- View bodies must compute quickly to meet frame deadlines; slow or frequent updates lead to hitches.
+- Instruments is the primary tool to find long-running updates and excessive update frequency.
+
+## Instruments workflow
+
+1. Profile via Product > Profile.
+2. Choose the SwiftUI template and record.
+3. Exercise the target interaction.
+4. Stop recording and inspect the SwiftUI track + Time Profiler.
+
+## SwiftUI timeline lanes
+
+- Update Groups: overview of time SwiftUI spends calculating updates.
+- Long View Body Updates: orange >500us, red >1000us.
+- Long Platform View Updates: AppKit/UIKit hosting in SwiftUI.
+- Other Long Updates: geometry/text/layout and other SwiftUI work.
+- Hitches: frame misses where UI wasn’t ready in time.
+
+## Diagnose long view body updates
+
+- Expand the SwiftUI track; inspect module-specific subtracks.
+- Set Inspection Range and correlate with Time Profiler.
+- Use call tree or flame graph to identify expensive frames.
+- Repeat the update to gather enough samples for analysis.
+- Filter to a specific update (Show Calls Made by `MySwiftUIView.body`).
+
+## Diagnose frequent updates
+
+- Use Update Groups to find long active groups without long updates.
+- Set inspection range on the group and analyze update counts.
+- Use Cause graph ("Show Causes") to see what triggers updates.
+- Compare causes with expected data flow; prioritize the highest-frequency causes.
+
+## Remediation patterns
+
+- Move expensive work out of `body` and cache results.
+- Use `Observable()` macro to scope dependencies to properties actually read.
+- Avoid broad dependencies that fan out updates to many views.
+- Reduce layout churn; isolate state-dependent subtrees from layout readers.
+- Avoid storing closures that capture parent state; precompute child views.
+- Gate frequent updates (e.g., geometry changes) by thresholds.
+
+## Verification
+
+- Re-record after changes to confirm reduced update counts and fewer hitches.

package/bundled-skills/swiftui-ui-patterns/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: swiftui-ui-patterns
+description: Apply proven SwiftUI UI patterns for navigation, sheets, async state, and reusable screens.
+risk: safe
+source: "Dimillian/Skills (MIT)"
+date_added: "2026-03-25"
+---
+
+# SwiftUI UI Patterns
+
+## Quick start
+
+## When to Use
+
+- When creating or refactoring SwiftUI screens, flows, or reusable UI components.
+- When you need guidance on navigation, sheets, async state, previews, or component patterns.
+
+Choose a track based on your goal:
+
+### Existing project
+
+- Identify the feature or screen and the primary interaction model (list, detail, editor, settings, tabbed).
+- Find a nearby example in the repo with `rg "TabView\("` or similar, then read the closest SwiftUI view.
+- Apply local conventions: prefer SwiftUI-native state, keep state local when possible, and use environment injection for shared dependencies.
+- Choose the relevant component reference from `references/components-index.md` and follow its guidance.
+- If the interaction reveals secondary content by dragging or scrolling the primary content away, read `references/scroll-reveal.md` before implementing gestures manually.
+- Build the view with small, focused subviews and SwiftUI-native data flow.
+
+### New project scaffolding
+
+- Start with `references/app-wiring.md` to wire TabView + NavigationStack + sheets.
+- Add a minimal `AppTab` and `RouterPath` based on the provided skeletons.
+- Choose the next component reference based on the UI you need first (TabView, NavigationStack, Sheets).
+- Expand the route and sheet enums as new screens are added.
+
+## General rules to follow
+
+- Use modern SwiftUI state (`@State`, `@Binding`, `@Observable`, `@Environment`) and avoid unnecessary view models.
+- If the deployment target includes iOS 16 or earlier and cannot use the Observation API introduced in iOS 17, fall back to `ObservableObject` with `@StateObject` for root ownership, `@ObservedObject` for injected observation, and `@EnvironmentObject` only for truly shared app-level state.
+- Prefer composition; keep views small and focused.
+- Use async/await with `.task` and explicit loading/error states. For restart, cancellation, and debouncing guidance, read `references/async-state.md`.
+- Keep shared app services in `@Environment`, but prefer explicit initializer injection for feature-local dependencies and models. For root wiring patterns, read `references/app-wiring.md`.
+- Prefer the newest SwiftUI API that fits the deployment target and call out the minimum OS whenever a pattern depends on it.
+- Maintain existing legacy patterns only when editing legacy files.
+- Follow the project's formatter and style guide.
+- **Sheets**: Prefer `.sheet(item:)` over `.sheet(isPresented:)` when state represents a selected model. Avoid `if let` inside a sheet body. Sheets should own their actions and call `dismiss()` internally instead of forwarding `onCancel`/`onConfirm` closures.
+- **Scroll-driven reveals**: Prefer deriving a normalized progress value from scroll offset and driving the visual state from that single source of truth. Avoid parallel gesture state machines unless scroll alone cannot express the interaction.
+
+## State ownership summary
+
+Use the narrowest state tool that matches the ownership model:
+
+| Scenario | Preferred pattern |
+| --- | --- |
+| Local UI state owned by one view | `@State` |
+| Child mutates parent-owned value state | `@Binding` |
+| Root-owned reference model on iOS 17+ | `@State` with an `@Observable` type |
+| Child reads or mutates an injected `@Observable` model on iOS 17+ | Pass it explicitly as a stored property |
+| Shared app service or configuration | `@Environment(Type.self)` |
+| Legacy reference model on iOS 16 and earlier | `@StateObject` at the root, `@ObservedObject` when injected |
+
+Choose the ownership location first, then pick the wrapper. Do not introduce a reference model when plain value state is enough.
+
+## Cross-cutting references
+
+- `references/navigationstack.md`: navigation ownership, per-tab history, and enum routing.
+- `references/sheets.md`: centralized modal presentation and enum-driven sheets.
+- `references/deeplinks.md`: URL handling and routing external links into app destinations.
+- `references/app-wiring.md`: root dependency graph, environment usage, and app shell wiring.
+- `references/async-state.md`: `.task`, `.task(id:)`, cancellation, debouncing, and async UI state.
+- `references/previews.md`: `#Preview`, fixtures, mock environments, and isolated preview setup.
+- `references/performance.md`: stable identity, observation scope, lazy containers, and render-cost guardrails.
+
+## Anti-patterns
+
+- Giant views that mix layout, business logic, networking, routing, and formatting in one file.
+- Multiple boolean flags for mutually exclusive sheets, alerts, or navigation destinations.
+- Live service calls directly inside `body`-driven code paths instead of view lifecycle hooks or injected models/services.
+- Reaching for `AnyView` to work around type mismatches that should be solved with better composition.
+- Defaulting every shared dependency to `@EnvironmentObject` or a global router without a clear ownership reason.
+
+## Workflow for a new SwiftUI view
+
+1. Define the view's state, ownership location, and minimum OS assumptions before writing UI code.
+2. Identify which dependencies belong in `@Environment` and which should stay as explicit initializer inputs.
+3. Sketch the view hierarchy, routing model, and presentation points; extract repeated parts into subviews. For complex navigation, read `references/navigationstack.md`, `references/sheets.md`, or `references/deeplinks.md`. **Build and verify no compiler errors before proceeding.**
+4. Implement async loading with `.task` or `.task(id:)`, plus explicit loading and error states when needed. Read `references/async-state.md` when the work depends on changing inputs or cancellation.
+5. Add previews for the primary and secondary states, then add accessibility labels or identifiers when the UI is interactive. Read `references/previews.md` when the view needs fixtures or injected mock dependencies.
+6. Validate with a build: confirm no compiler errors, check that previews render without crashing, ensure state changes propagate correctly, and sanity-check that list identity and observation scope will not cause avoidable re-renders. Read `references/performance.md` if the screen is large, scroll-heavy, or frequently updated. For common SwiftUI compilation errors — missing `@State` annotations, ambiguous `ViewBuilder` closures, or mismatched generic types — resolve them before updating callsites. **If the build fails:** read the error message carefully, fix the identified issue, then rebuild before proceeding to the next step. If a preview crashes, isolate the offending subview, confirm its state initialisation is valid, and re-run the preview before continuing.
+
+## Component references
+
+Use `references/components-index.md` as the entry point. Each component reference should include:
+- Intent and best-fit scenarios.
+- Minimal usage pattern with local conventions.
+- Pitfalls and performance notes.
+- Paths to existing examples in the current repo.
+
+## Adding a new component reference
+
+- Create `references/<component>.md`.
+- Keep it short and actionable; link to concrete files in the current repo.
+- Update `references/components-index.md` with the new entry.

package/bundled-skills/swiftui-ui-patterns/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SwiftUI UI Patterns"
+  short_description: "Apply practical SwiftUI UI patterns"
+  default_prompt: "Use $swiftui-ui-patterns to design or refactor this SwiftUI UI with strong default patterns."

package/bundled-skills/swiftui-ui-patterns/references/app-wiring.md

@@ -0,0 +1,201 @@
+# App wiring and dependency graph
+
+## Intent
+
+Show how to wire the app shell (TabView + NavigationStack + sheets) and install a global dependency graph (environment objects, services, streaming clients, SwiftData ModelContainer) in one place.
+
+## Recommended structure
+
+1) Root view sets up tabs, per-tab routers, and sheets.
+2) A dedicated view modifier installs global dependencies and lifecycle tasks (auth state, streaming watchers, push tokens, data containers).
+3) Feature views pull only what they need from the environment; feature-specific state stays local.
+
+## Dependency selection
+
+- Use `@Environment` for app-level services, shared clients, theme/configuration, and values that many descendants genuinely need.
+- Prefer initializer injection for feature-local dependencies and models. Do not move a dependency into the environment just to avoid passing one or two arguments.
+- Keep mutable feature state out of the environment unless it is intentionally shared across broad parts of the app.
+- Use `@EnvironmentObject` only as a legacy fallback or when the project already standardizes on it for a truly shared object.
+
+## Root shell example (generic)
+
+```swift
+@MainActor
+struct AppView: View {
+  @State private var selectedTab: AppTab = .home
+  @State private var tabRouter = TabRouter()
+
+  var body: some View {
+    TabView(selection: $selectedTab) {
+      ForEach(AppTab.allCases) { tab in
+        let router = tabRouter.router(for: tab)
+        NavigationStack(path: tabRouter.binding(for: tab)) {
+          tab.makeContentView()
+        }
+        .withSheetDestinations(sheet: Binding(
+          get: { router.presentedSheet },
+          set: { router.presentedSheet = $0 }
+        ))
+        .environment(router)
+        .tabItem { tab.label }
+        .tag(tab)
+      }
+    }
+    .withAppDependencyGraph()
+  }
+}
+```
+
+Minimal `AppTab` example:
+
+```swift
+@MainActor
+enum AppTab: Identifiable, Hashable, CaseIterable {
+  case home, notifications, settings
+  var id: String { String(describing: self) }
+
+  @ViewBuilder
+  func makeContentView() -> some View {
+    switch self {
+    case .home: HomeView()
+    case .notifications: NotificationsView()
+    case .settings: SettingsView()
+    }
+  }
+
+  @ViewBuilder
+  var label: some View {
+    switch self {
+    case .home: Label("Home", systemImage: "house")
+    case .notifications: Label("Notifications", systemImage: "bell")
+    case .settings: Label("Settings", systemImage: "gear")
+    }
+  }
+}
+```
+
+Router skeleton:
+
+```swift
+@MainActor
+@Observable
+final class RouterPath {
+  var path: [Route] = []
+  var presentedSheet: SheetDestination?
+}
+
+enum Route: Hashable {
+  case detail(id: String)
+}
+```
+
+## Dependency graph modifier (generic)
+
+Use a single modifier to install environment objects and handle lifecycle hooks when the active account/client changes. This keeps wiring consistent and avoids forgetting a dependency in call sites.
+
+```swift
+extension View {
+  func withAppDependencyGraph(
+    accountManager: AccountManager = .shared,
+    currentAccount: CurrentAccount = .shared,
+    currentInstance: CurrentInstance = .shared,
+    userPreferences: UserPreferences = .shared,
+    theme: Theme = .shared,
+    watcher: StreamWatcher = .shared,
+    pushNotifications: PushNotificationsService = .shared,
+    intentService: AppIntentService = .shared,
+    quickLook: QuickLook = .shared,
+    toastCenter: ToastCenter = .shared,
+    namespace: Namespace.ID? = nil,
+    isSupporter: Bool = false
+  ) -> some View {
+    environment(accountManager)
+      .environment(accountManager.currentClient)
+      .environment(quickLook)
+      .environment(currentAccount)
+      .environment(currentInstance)
+      .environment(userPreferences)
+      .environment(theme)
+      .environment(watcher)
+      .environment(pushNotifications)
+      .environment(intentService)
+      .environment(toastCenter)
+      .environment(\.isSupporter, isSupporter)
+      .task(id: accountManager.currentClient.id) {
+        let client = accountManager.currentClient
+        if let namespace { quickLook.namespace = namespace }
+        currentAccount.setClient(client: client)
+        currentInstance.setClient(client: client)
+        userPreferences.setClient(client: client)
+        await currentInstance.fetchCurrentInstance()
+        watcher.setClient(client: client, instanceStreamingURL: currentInstance.instance?.streamingURL)
+        if client.isAuth {
+          watcher.watch(streams: [.user, .direct])
+        } else {
+          watcher.stopWatching()
+        }
+      }
+      .task(id: accountManager.pushAccounts.map(\.token)) {
+        pushNotifications.tokens = accountManager.pushAccounts.map(\.token)
+      }
+  }
+}
+```
+
+Notes:
+- The `.task(id:)` hooks respond to account/client changes, re-seeding services and watcher state.
+- Keep the modifier focused on global wiring; feature-specific state stays within features.
+- Adjust types (AccountManager, StreamWatcher, etc.) to match your project.
+
+## SwiftData / ModelContainer
+
+Install your `ModelContainer` at the root so all feature views share the same store. Keep the list minimal to the models that need persistence.
+
+```swift
+extension View {
+  func withModelContainer() -> some View {
+    modelContainer(for: [Draft.self, LocalTimeline.self, TagGroup.self])
+  }
+}
+```
+
+Why: a single container avoids duplicated stores per sheet or tab and keeps data consistent.
+
+## Sheet routing (enum-driven)
+
+Centralize sheets with a small enum and a helper modifier.
+
+```swift
+enum SheetDestination: Identifiable {
+  case composer
+  case settings
+  var id: String { String(describing: self) }
+}
+
+extension View {
+  func withSheetDestinations(sheet: Binding<SheetDestination?>) -> some View {
+    sheet(item: sheet) { destination in
+      switch destination {
+      case .composer:
+        ComposerView().withEnvironments()
+      case .settings:
+        SettingsView().withEnvironments()
+      }
+    }
+  }
+}
+```
+
+Why: enum-driven sheets keep presentation centralized and testable; adding a new sheet means adding one enum case and one switch branch.
+
+## When to use
+
+- Apps with multiple packages/modules that share environment objects and services.
+- Apps that need to react to account/client changes and rewire streaming/push safely.
+- Any app that wants consistent TabView + NavigationStack + sheet wiring without repeating environment setup.
+
+## Caveats
+
+- Keep the dependency modifier slim; do not put feature state or heavy logic there.
+- Ensure `.task(id:)` work is lightweight or cancelled appropriately; long-running work belongs in services.
+- If unauthenticated clients exist, gate streaming/watch calls to avoid reconnect spam.

package/bundled-skills/swiftui-ui-patterns/references/async-state.md

@@ -0,0 +1,96 @@
+# Async state and task lifecycle
+
+## Intent
+
+Use this pattern when a view loads data, reacts to changing input, or coordinates async work that should follow the SwiftUI view lifecycle.
+
+## Core rules
+
+- Use `.task` for load-on-appear work that belongs to the view lifecycle.
+- Use `.task(id:)` when async work should restart for a changing input such as a query, selection, or identifier.
+- Treat cancellation as a normal path for view-driven tasks. Check `Task.isCancelled` in longer flows and avoid surfacing cancellation as a user-facing error.
+- Debounce or coalesce user-driven async work such as search before it fans out into repeated requests.
+- Keep UI-facing models and mutations main-actor-safe; do background work in services, then publish the result back to UI state.
+
+## Example: load on appear
+
+```swift
+struct DetailView: View {
+  let id: String
+  @State private var state: LoadState<Item> = .idle
+  @Environment(ItemClient.self) private var client
+
+  var body: some View {
+    content
+      .task {
+        await load()
+      }
+  }
+
+  @ViewBuilder
+  private var content: some View {
+    switch state {
+    case .idle, .loading:
+      ProgressView()
+    case .loaded(let item):
+      ItemContent(item: item)
+    case .failed(let error):
+      ErrorView(error: error)
+    }
+  }
+
+  private func load() async {
+    state = .loading
+    do {
+      state = .loaded(try await client.fetch(id: id))
+    } catch is CancellationError {
+      return
+    } catch {
+      state = .failed(error)
+    }
+  }
+}
+```
+
+## Example: restart on input change
+
+```swift
+struct SearchView: View {
+  @State private var query = ""
+  @State private var results: [ResultItem] = []
+  @Environment(SearchClient.self) private var client
+
+  var body: some View {
+    List(results) { item in
+      Text(item.title)
+    }
+    .searchable(text: $query)
+    .task(id: query) {
+      try? await Task.sleep(for: .milliseconds(250))
+      guard !Task.isCancelled, !query.isEmpty else {
+        results = []
+        return
+      }
+      do {
+        results = try await client.search(query)
+      } catch is CancellationError {
+        return
+      } catch {
+        results = []
+      }
+    }
+  }
+}
+```
+
+## When to move work out of the view
+
+- If the async flow spans multiple screens or must survive view dismissal, move it into a service or model.
+- If the view is mostly coordinating app-level lifecycle or account changes, wire it at the app shell in `app-wiring.md`.
+- If retry, caching, or offline policy becomes complex, keep the policy in the client/service and leave the view with simple state transitions.
+
+## Pitfalls
+
+- Do not start network work directly from `body`.
+- Do not ignore cancellation for searches, typeahead, or rapidly changing selections.
+- Avoid storing derived async state in multiple places when one source of truth is enough.