codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/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/templates/.agent/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.

package/templates/.agent/skills/swiftui-ui-patterns/references/components-index.md

@@ -0,0 +1,50 @@
+# Components Index
+
+Use this file to find component and cross-cutting guidance. Each entry lists when to use it.
+
+## Available components
+
+- TabView: `references/tabview.md` — Use when building a tab-based app or any tabbed feature set.
+- NavigationStack: `references/navigationstack.md` — Use when you need push navigation and programmatic routing, especially per-tab history.
+- Sheets and presentation: `references/sheets.md` — Use for local item-driven sheets, centralized modal routing, and sheet-specific action patterns.
+- Form and Settings: `references/form.md` — Use for settings, grouped inputs, and structured data entry.
+- macOS Settings: `references/macos-settings.md` — Use when building a macOS Settings window with SwiftUI's Settings scene.
+- Split views and columns: `references/split-views.md` — Use for iPad/macOS multi-column layouts or custom secondary columns.
+- List and Section: `references/list.md` — Use for feed-style content and settings rows.
+- ScrollView and Lazy stacks: `references/scrollview.md` — Use for custom layouts, horizontal scrollers, or grids.
+- Scroll-reveal detail surfaces: `references/scroll-reveal.md` — Use when a detail screen reveals secondary content or actions as the user scrolls or swipes between full-screen sections.
+- Grids: `references/grids.md` — Use for icon pickers, media galleries, and tiled layouts.
+- Theming and dynamic type: `references/theming.md` — Use for app-wide theme tokens, colors, and type scaling.
+- Controls (toggles, pickers, sliders): `references/controls.md` — Use for settings controls and input selection.
+- Input toolbar (bottom anchored): `references/input-toolbar.md` — Use for chat/composer screens with a sticky input bar.
+- Top bar overlays (iOS 26+ and fallback): `references/top-bar.md` — Use for pinned selectors or pills above scroll content.
+- Overlay and toasts: `references/overlay.md` — Use for transient UI like banners or toasts.
+- Focus handling: `references/focus.md` — Use for chaining fields and keyboard focus management.
+- Searchable: `references/searchable.md` — Use for native search UI with scopes and async results.
+- Async images and media: `references/media.md` — Use for remote media, previews, and media viewers.
+- Haptics: `references/haptics.md` — Use for tactile feedback tied to key actions.
+- Matched transitions: `references/matched-transitions.md` — Use for smooth source-to-destination animations.
+- Deep links and URL routing: `references/deeplinks.md` — Use for in-app navigation from URLs.
+- Title menus: `references/title-menus.md` — Use for filter or context menus in the navigation title.
+- Menu bar commands: `references/menu-bar.md` — Use when adding or customizing macOS/iPadOS menu bar commands.
+- Loading & placeholders: `references/loading-placeholders.md` — Use for redacted skeletons, empty states, and loading UX.
+- Lightweight clients: `references/lightweight-clients.md` — Use for small, closure-based API clients injected into stores.
+
+## Cross-cutting references
+
+- App wiring and dependency graph: `references/app-wiring.md` — Use to wire the app shell, install shared dependencies, and decide what belongs in the environment.
+- Async state and task lifecycle: `references/async-state.md` — Use when a view loads data, reacts to changing input, or needs cancellation/debouncing guidance.
+- Previews: `references/previews.md` — Use when adding `#Preview`, fixtures, mock environments, or isolated preview setup.
+- Performance guardrails: `references/performance.md` — Use when a screen is large, scroll-heavy, frequently updated, or showing signs of avoidable re-renders.
+
+## Planned components (create files as needed)
+
+- Web content: create `references/webview.md` — Use for embedded web content or in-app browsing.
+- Status composer patterns: create `references/composer.md` — Use for composition or editor workflows.
+- Text input and validation: create `references/text-input.md` — Use for forms, validation, and text-heavy input.
+- Design system usage: create `references/design-system.md` — Use when applying shared styling rules.
+
+## Adding entries
+
+- Add the component file and link it here with a short “when to use” description.
+- Keep each component reference short and actionable.

package/templates/.agent/skills/swiftui-ui-patterns/references/controls.md

@@ -0,0 +1,57 @@
+# Controls (Toggle, Slider, Picker)
+
+## Intent
+
+Use native controls for settings and configuration screens, keeping labels accessible and state bindings clear.
+
+## Core patterns
+
+- Bind controls directly to `@State`, `@Binding`, or `@AppStorage`.
+- Prefer `Toggle` for boolean preferences.
+- Use `Slider` for numeric ranges and show the current value in a label.
+- Use `Picker` for discrete choices; use `.pickerStyle(.segmented)` only for 2–4 options.
+- Keep labels visible and descriptive; avoid embedding buttons inside controls.
+
+## Example: toggles with sections
+
+```swift
+Form {
+  Section("Notifications") {
+    Toggle("Mentions", isOn: $preferences.notificationsMentionsEnabled)
+    Toggle("Follows", isOn: $preferences.notificationsFollowsEnabled)
+    Toggle("Boosts", isOn: $preferences.notificationsBoostsEnabled)
+  }
+}
+```
+
+## Example: slider with value text
+
+```swift
+Section("Font Size") {
+  Slider(value: $fontSizeScale, in: 0.5...1.5, step: 0.1)
+  Text("Scale: \(String(format: \"%.1f\", fontSizeScale))")
+    .font(.scaledBody)
+}
+```
+
+## Example: picker for enums
+
+```swift
+Picker("Default Visibility", selection: $visibility) {
+  ForEach(Visibility.allCases, id: \.self) { option in
+    Text(option.title).tag(option)
+  }
+}
+```
+
+## Design choices to keep
+
+- Group related controls in a `Form` section.
+- Use `.disabled(...)` to reflect locked or inherited settings.
+- Use `Label` inside toggles to combine icon + text when it adds clarity.
+
+## Pitfalls
+
+- Avoid `.pickerStyle(.segmented)` for large sets; use menu or inline styles instead.
+- Don’t hide labels for sliders; always show context.
+- Avoid hard-coding colors for controls; use theme tint sparingly.

package/templates/.agent/skills/swiftui-ui-patterns/references/deeplinks.md

@@ -0,0 +1,66 @@
+# Deep links and navigation
+
+## Intent
+
+Route external URLs into in-app destinations while falling back to system handling when needed.
+
+## Core patterns
+
+- Centralize URL handling in the router (`handle(url:)`, `handleDeepLink(url:)`).
+- Inject an `OpenURLAction` handler that delegates to the router.
+- Use `.onOpenURL` for app scheme links and convert them to web URLs if needed.
+- Let the router decide whether to navigate or open externally.
+
+## Example: router entry points
+
+```swift
+@MainActor
+final class RouterPath {
+  var path: [Route] = []
+  var urlHandler: ((URL) -> OpenURLAction.Result)?
+
+  func handle(url: URL) -> OpenURLAction.Result {
+    if isInternal(url) {
+      navigate(to: .status(id: url.lastPathComponent))
+      return .handled
+    }
+    return urlHandler?(url) ?? .systemAction
+  }
+
+  func handleDeepLink(url: URL) -> OpenURLAction.Result {
+    // Resolve federated URLs, then navigate.
+    navigate(to: .status(id: url.lastPathComponent))
+    return .handled
+  }
+}
+```
+
+## Example: attach to a root view
+
+```swift
+extension View {
+  func withLinkRouter(_ router: RouterPath) -> some View {
+    self
+      .environment(
+        \.openURL,
+        OpenURLAction { url in
+          router.handle(url: url)
+        }
+      )
+      .onOpenURL { url in
+        router.handleDeepLink(url: url)
+      }
+  }
+}
+```
+
+## Design choices to keep
+
+- Keep URL parsing and decision logic inside the router.
+- Avoid handling deep links in multiple places; one entry point is enough.
+- Always provide a fallback to `OpenURLAction` or `UIApplication.shared.open`.
+
+## Pitfalls
+
+- Don’t assume the URL is internal; validate first.
+- Avoid blocking UI while resolving remote links; use `Task`.

package/templates/.agent/skills/swiftui-ui-patterns/references/focus.md

@@ -0,0 +1,90 @@
+# Focus handling and field chaining
+
+## Intent
+
+Use `@FocusState` to control keyboard focus, chain fields, and coordinate focus across complex forms.
+
+## Core patterns
+
+- Use an enum to represent focusable fields.
+- Set initial focus in `onAppear`.
+- Use `.onSubmit` to move focus to the next field.
+- For dynamic lists of fields, use an enum with associated values (e.g., `.option(Int)`).
+
+## Example: single field focus
+
+```swift
+struct AddServerView: View {
+  @State private var server = ""
+  @FocusState private var isServerFieldFocused: Bool
+
+  var body: some View {
+    Form {
+      TextField("Server", text: $server)
+        .focused($isServerFieldFocused)
+    }
+    .onAppear { isServerFieldFocused = true }
+  }
+}
+```
+
+## Example: chained focus with enum
+
+```swift
+struct EditTagView: View {
+  enum FocusField { case title, symbol, newTag }
+  @FocusState private var focusedField: FocusField?
+
+  var body: some View {
+    Form {
+      TextField("Title", text: $title)
+        .focused($focusedField, equals: .title)
+        .onSubmit { focusedField = .symbol }
+
+      TextField("Symbol", text: $symbol)
+        .focused($focusedField, equals: .symbol)
+        .onSubmit { focusedField = .newTag }
+    }
+    .onAppear { focusedField = .title }
+  }
+}
+```
+
+## Example: dynamic focus for variable fields
+
+```swift
+struct PollView: View {
+  enum FocusField: Hashable { case option(Int) }
+  @FocusState private var focused: FocusField?
+  @State private var options: [String] = ["", ""]
+  @State private var currentIndex = 0
+
+  var body: some View {
+    ForEach(options.indices, id: \.self) { index in
+      TextField("Option \(index + 1)", text: $options[index])
+        .focused($focused, equals: .option(index))
+        .onSubmit { addOption(at: index) }
+    }
+    .onAppear { focused = .option(0) }
+  }
+
+  private func addOption(at index: Int) {
+    options.append("")
+    currentIndex = index + 1
+    DispatchQueue.main.asyncAfter(deadline: .now() + 0.01) {
+      focused = .option(currentIndex)
+    }
+  }
+}
+```
+
+## Design choices to keep
+
+- Keep focus state local to the view that owns the fields.
+- Use focus changes to drive UX (validation messages, helper UI).
+- Pair with `.scrollDismissesKeyboard(...)` when using ScrollView/Form.
+
+## Pitfalls
+
+- Don’t store focus state in shared objects; it is view-local.
+- Avoid aggressive focus changes during animation; delay if needed.

package/templates/.agent/skills/swiftui-ui-patterns/references/form.md

@@ -0,0 +1,97 @@
+# Form
+
+## Intent
+
+Use `Form` for structured settings, grouped inputs, and action rows. This pattern keeps layout, spacing, and accessibility consistent for data entry screens.
+
+## Core patterns
+
+- Wrap the form in a `NavigationStack` only when it is presented in a sheet or standalone view without an existing navigation context.
+- Group related controls into `Section` blocks.
+- Use `.scrollContentBackground(.hidden)` plus a custom background color when you need design-system colors.
+- Apply `.formStyle(.grouped)` for grouped styling when appropriate.
+- Use `@FocusState` to manage keyboard focus in input-heavy forms.
+
+## Example: settings-style form
+
+```swift
+@MainActor
+struct SettingsView: View {
+  @Environment(Theme.self) private var theme
+
+  var body: some View {
+    NavigationStack {
+      Form {
+        Section("General") {
+          NavigationLink("Display") { DisplaySettingsView() }
+          NavigationLink("Haptics") { HapticsSettingsView() }
+        }
+
+        Section("Account") {
+          Button("Edit profile") { /* open sheet */ }
+            .buttonStyle(.plain)
+        }
+        .listRowBackground(theme.primaryBackgroundColor)
+      }
+      .navigationTitle("Settings")
+      .navigationBarTitleDisplayMode(.inline)
+      .scrollContentBackground(.hidden)
+      .background(theme.secondaryBackgroundColor)
+    }
+  }
+}
+```
+
+## Example: modal form with validation
+
+```swift
+@MainActor
+struct AddRemoteServerView: View {
+  @Environment(\.dismiss) private var dismiss
+  @Environment(Theme.self) private var theme
+
+  @State private var server: String = ""
+  @State private var isValid = false
+  @FocusState private var isServerFieldFocused: Bool
+
+  var body: some View {
+    NavigationStack {
+      Form {
+        TextField("Server URL", text: $server)
+          .keyboardType(.URL)
+          .textInputAutocapitalization(.never)
+          .autocorrectionDisabled()
+          .focused($isServerFieldFocused)
+          .listRowBackground(theme.primaryBackgroundColor)
+
+        Button("Add") {
+          guard isValid else { return }
+          dismiss()
+        }
+        .disabled(!isValid)
+        .listRowBackground(theme.primaryBackgroundColor)
+      }
+      .formStyle(.grouped)
+      .navigationTitle("Add Server")
+      .navigationBarTitleDisplayMode(.inline)
+      .scrollContentBackground(.hidden)
+      .background(theme.secondaryBackgroundColor)
+      .scrollDismissesKeyboard(.immediately)
+      .toolbar { CancelToolbarItem() }
+      .onAppear { isServerFieldFocused = true }
+    }
+  }
+}
+```
+
+## Design choices to keep
+
+- Prefer `Form` over custom stacks for settings and input screens.
+- Keep rows tappable by using `.contentShape(Rectangle())` and `.buttonStyle(.plain)` on row buttons.
+- Use list row backgrounds to keep section styling consistent with your theme.
+
+## Pitfalls
+
+- Avoid heavy custom layouts inside a `Form`; it can lead to spacing issues.
+- If you need highly custom layouts, prefer `ScrollView` + `VStack`.
+- Don’t mix multiple background strategies; pick either default Form styling or custom colors.