claudecode-omc 5.6.6 → 5.6.8

package/.local/skills/swiftui-ui-patterns/references/overlay.md

@@ -0,0 +1,45 @@
+# Overlay and toasts
+
+## Intent
+
+Use overlays for transient UI (toasts, banners, loaders) without affecting layout.
+
+## Core patterns
+
+- Use `.overlay(alignment:)` to place global UI without changing the underlying layout.
+- Keep overlays lightweight and dismissible.
+- Use a dedicated `ToastCenter` (or similar) for global state if multiple features trigger toasts.
+
+## Example: toast overlay
+
+```swift
+struct AppRootView: View {
+  @State private var toast: Toast?
+
+  var body: some View {
+    content
+      .overlay(alignment: .top) {
+        if let toast {
+          ToastView(toast: toast)
+            .transition(.move(edge: .top).combined(with: .opacity))
+            .onAppear {
+              DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
+                withAnimation { self.toast = nil }
+              }
+            }
+        }
+      }
+  }
+}
+```
+
+## Design choices to keep
+
+- Prefer overlays for transient UI rather than embedding in layout stacks.
+- Use transitions and short auto-dismiss timers.
+- Keep the overlay aligned to a clear edge (`.top` or `.bottom`).
+
+## Pitfalls
+
+- Avoid overlays that block all interaction unless explicitly needed.
+- Don’t stack many overlays; use a queue or replace the current toast.

package/.local/skills/swiftui-ui-patterns/references/performance.md

@@ -0,0 +1,62 @@
+# Performance guardrails
+
+## Intent
+
+Use these rules when a SwiftUI screen is large, scroll-heavy, frequently updated, or at risk of unnecessary recomputation.
+
+## Core rules
+
+- Give `ForEach` and list content stable identity. Do not use unstable indices as identity when the collection can reorder or mutate.
+- Keep expensive filtering, sorting, and formatting out of `body`; precompute or move it into a model/helper when it is not trivial.
+- Narrow observation scope so only the views that read changing state need to update.
+- Prefer lazy containers for larger scrolling content and extract subviews when only part of a screen changes frequently.
+- Avoid swapping entire top-level view trees for small state changes; keep a stable root view and vary localized sections or modifiers.
+
+## Example: stable identity
+
+```swift
+ForEach(items) { item in
+  Row(item: item)
+}
+```
+
+Prefer that over index-based identity when the collection can change order:
+
+```swift
+ForEach(Array(items.enumerated()), id: \.offset) { _, item in
+  Row(item: item)
+}
+```
+
+## Example: move expensive work out of body
+
+```swift
+struct FeedView: View {
+  let items: [FeedItem]
+
+  private var sortedItems: [FeedItem] {
+    items.sorted(using: KeyPathComparator(\.createdAt, order: .reverse))
+  }
+
+  var body: some View {
+    List(sortedItems) { item in
+      FeedRow(item: item)
+    }
+  }
+}
+```
+
+If the work is more expensive than a small derived property, move it into a model, store, or helper that updates less often.
+
+## When to investigate further
+
+- Janky scrolling in long feeds or grids
+- Typing lag from search or form validation
+- Overly broad view updates when one small piece of state changes
+- Large screens with many conditionals or repeated formatting work
+
+## Pitfalls
+
+- Recomputing heavy transforms every render
+- Observing a large object from many descendants when only one field matters
+- Building custom scroll containers when `List`, `LazyVStack`, or `LazyHGrid` would already solve the problem

package/.local/skills/swiftui-ui-patterns/references/previews.md

@@ -0,0 +1,48 @@
+# Previews
+
+## Intent
+
+Use previews to validate layout, state wiring, and injected dependencies without relying on a running app or live services.
+
+## Core rules
+
+- Add `#Preview` coverage for the primary state plus important secondary states such as loading, empty, and error.
+- Use deterministic fixtures, mocks, and sample data. Do not make previews depend on live network calls, real databases, or global singletons.
+- Install required environment dependencies directly in the preview so the view can render in isolation.
+- Keep preview setup close to the view until it becomes noisy; then extract lightweight preview helpers or fixtures.
+- If a preview crashes, fix the state initialization or dependency wiring before expanding the feature further.
+
+## Example: simple preview states
+
+```swift
+#Preview("Loaded") {
+  ProfileView(profile: .fixture)
+}
+
+#Preview("Empty") {
+  ProfileView(profile: nil)
+}
+```
+
+## Example: preview with injected dependencies
+
+```swift
+#Preview("Search results") {
+  SearchView()
+    .environment(SearchClient.preview(results: [.fixture, .fixture2]))
+    .environment(Theme.preview)
+}
+```
+
+## Preview checklist
+
+- Does the preview install every required environment dependency?
+- Does it cover at least one success path and one non-happy path?
+- Are fixtures stable and small enough to be read quickly?
+- Can the preview render without network, auth, or app-global initialization?
+
+## Pitfalls
+
+- Do not hide preview crashes by making dependencies optional if the production view requires them.
+- Avoid huge inline fixtures when a named sample is easier to read.
+- Do not couple previews to global shared singletons unless the project has no alternative.

package/.local/skills/swiftui-ui-patterns/references/scroll-reveal.md

@@ -0,0 +1,133 @@
+# Scroll-reveal detail surfaces
+
+## Intent
+
+Use this pattern when a detail screen has a primary surface first and secondary content behind it, and you want the user to reveal that secondary layer by scrolling or swiping instead of tapping a separate button.
+
+Typical fits:
+
+- media detail screens that reveal actions or metadata
+- maps, cards, or canvases that transition into structured detail
+- full-screen viewers with a second "actions" or "insights" page
+
+## Core pattern
+
+Build the interaction as a paged vertical `ScrollView` with two sections:
+
+1. a primary section sized to the viewport
+2. a secondary section below it
+
+Derive a normalized `progress` value from the vertical content offset and drive all visual changes from that one value.
+
+Avoid treating the reveal as a separate gesture system unless scroll alone cannot express it.
+
+## Minimal structure
+
+```swift
+private enum DetailSection: Hashable {
+  case primary
+  case secondary
+}
+
+struct DetailSurface: View {
+  @State private var revealProgress: CGFloat = 0
+  @State private var secondaryHeight: CGFloat = 1
+
+  var body: some View {
+    GeometryReader { geometry in
+      ScrollViewReader { proxy in
+        ScrollView(.vertical, showsIndicators: false) {
+          VStack(spacing: 0) {
+            PrimaryContent(progress: revealProgress)
+              .frame(height: geometry.size.height)
+              .id(DetailSection.primary)
+
+            SecondaryContent(progress: revealProgress)
+              .id(DetailSection.secondary)
+              .onGeometryChange(for: CGFloat.self) { geo in
+                geo.size.height
+              } action: { newHeight in
+                secondaryHeight = max(newHeight, 1)
+              }
+          }
+          .scrollTargetLayout()
+        }
+        .scrollTargetBehavior(.paging)
+        .onScrollGeometryChange(for: CGFloat.self, of: { scroll in
+          scroll.contentOffset.y + scroll.contentInsets.top
+        }) { _, offset in
+          revealProgress = (offset / secondaryHeight).clamped(to: 0...1)
+        }
+        .safeAreaInset(edge: .bottom) {
+          ChevronAffordance(progress: revealProgress) {
+            withAnimation(.smooth) {
+              let target: DetailSection = revealProgress < 0.5 ? .secondary : .primary
+              proxy.scrollTo(target, anchor: .top)
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Design choices to keep
+
+- Make the primary section exactly viewport-sized when the interaction should feel like paging between states.
+- Compute `progress` from real scroll offset, not from duplicated booleans like `isExpanded`, `isShowingSecondary`, and `isSnapped`.
+- Use `progress` to drive `offset`, `opacity`, `blur`, `scaleEffect`, and toolbar state so the whole surface stays synchronized.
+- Use `ScrollViewReader` for programmatic snapping from taps on the primary content or chevron affordances.
+- Use `onScrollTargetVisibilityChange` when you need a settled section state for haptics, tooltip dismissal, analytics, or accessibility announcements.
+
+## Morphing a shared control
+
+If a control appears to move from the primary surface into the secondary content, do not render two fully visible copies.
+
+Instead:
+
+- expose a source anchor in the primary area
+- expose a destination anchor in the secondary area
+- render one overlay that interpolates position and size using `progress`
+
+```swift
+Color.clear
+  .anchorPreference(key: ControlAnchorKey.self, value: .bounds) { anchor in
+    ["source": anchor]
+  }
+
+Color.clear
+  .anchorPreference(key: ControlAnchorKey.self, value: .bounds) { anchor in
+    ["destination": anchor]
+  }
+
+.overlayPreferenceValue(ControlAnchorKey.self) { anchors in
+  MorphingControlOverlay(anchors: anchors, progress: revealProgress)
+}
+```
+
+This keeps the motion coherent and avoids duplicate-hit-target bugs.
+
+## Haptics and affordances
+
+- Use light threshold haptics when the reveal begins and stronger haptics near the committed state.
+- Keep a visible affordance like a chevron or pill while `progress` is near zero.
+- Flip, fade, or blur the affordance as the secondary section becomes active.
+
+## Interaction guards
+
+- Disable vertical scrolling when a conflicting mode is active, such as pinch-to-zoom, crop, or full-screen media manipulation.
+- Disable hit testing on overlays that should disappear once the secondary content is revealed.
+- Avoid same-axis nested scroll views unless the inner view is effectively static or disabled during the reveal.
+
+## Pitfalls
+
+- Do not hard-code the progress divisor. Measure the secondary section height or another real reveal distance.
+- Do not mix multiple animation sources for the same property. If `progress` drives it, keep other animations off that property.
+- Do not store derived state like `isSecondaryVisible` unless another API requires it. Prefer deriving it from `progress` or visible scroll targets.
+- Beware of layout feedback loops when measuring heights. Clamp zero values and update only when the measured height actually changes.
+
+## Concrete example
+
+- Pool iOS tile detail reveal: `/Users/dimillian/Documents/Dev/Pool/pool-ios/Pool/Sources/Features/Tile/Detail/TileDetailView.swift`
+- Secondary content anchor example: `/Users/dimillian/Documents/Dev/Pool/pool-ios/Pool/Sources/Features/Tile/Detail/TileDetailIntentListView.swift`

package/.local/skills/swiftui-ui-patterns/references/scrollview.md

@@ -0,0 +1,87 @@
+# ScrollView and Lazy stacks
+
+## Intent
+
+Use `ScrollView` with `LazyVStack`, `LazyHStack`, or `LazyVGrid` when you need custom layout, mixed content, or horizontal/ grid-based scrolling.
+
+## Core patterns
+
+- Prefer `ScrollView` + `LazyVStack` for chat-like or custom feed layouts.
+- Use `ScrollView(.horizontal)` + `LazyHStack` for chips, tags, avatars, and media strips.
+- Use `LazyVGrid` for icon/media grids; prefer adaptive columns when possible.
+- Use `ScrollViewReader` for scroll-to-top/bottom and anchor-based jumps.
+- Use `safeAreaInset(edge:)` for input bars that should stick above the keyboard.
+
+## Example: vertical custom feed
+
+```swift
+@MainActor
+struct ConversationView: View {
+  private enum Constants { static let bottomAnchor = "bottom" }
+  @State private var scrollProxy: ScrollViewProxy?
+
+  var body: some View {
+    ScrollViewReader { proxy in
+      ScrollView {
+        LazyVStack {
+          ForEach(messages) { message in
+            MessageRow(message: message)
+              .id(message.id)
+          }
+          Color.clear.frame(height: 1).id(Constants.bottomAnchor)
+        }
+        .padding(.horizontal, .layoutPadding)
+      }
+      .safeAreaInset(edge: .bottom) {
+        MessageInputBar()
+      }
+      .onAppear {
+        scrollProxy = proxy
+        withAnimation {
+          proxy.scrollTo(Constants.bottomAnchor, anchor: .bottom)
+        }
+      }
+    }
+  }
+}
+```
+
+## Example: horizontal chips
+
+```swift
+ScrollView(.horizontal, showsIndicators: false) {
+  LazyHStack(spacing: 8) {
+    ForEach(chips) { chip in
+      ChipView(chip: chip)
+    }
+  }
+}
+```
+
+## Example: adaptive grid
+
+```swift
+let columns = [GridItem(.adaptive(minimum: 120))]
+
+ScrollView {
+  LazyVGrid(columns: columns, spacing: 8) {
+    ForEach(items) { item in
+      GridItemView(item: item)
+    }
+  }
+  .padding(8)
+}
+```
+
+## Design choices to keep
+
+- Use `Lazy*` stacks when item counts are large or unknown.
+- Use non-lazy stacks for small, fixed-size content to avoid lazy overhead.
+- Keep IDs stable when using `ScrollViewReader`.
+- Prefer explicit animations (`withAnimation`) when scrolling to an ID.
+
+## Pitfalls
+
+- Avoid nesting scroll views of the same axis; it causes gesture conflicts.
+- Don’t combine `List` and `ScrollView` in the same hierarchy without a clear reason.
+- Overuse of `LazyVStack` for tiny content can add unnecessary complexity.

package/.local/skills/swiftui-ui-patterns/references/searchable.md

@@ -0,0 +1,71 @@
+# Searchable
+
+## Intent
+
+Use `searchable` to add native search UI with optional scopes and async results.
+
+## Core patterns
+
+- Bind `searchable(text:)` to local state.
+- Use `.searchScopes` for multiple search modes.
+- Use `.task(id: searchQuery)` or debounced tasks to avoid overfetching.
+- Show placeholders or progress states while results load.
+
+## Example: searchable with scopes
+
+```swift
+@MainActor
+struct ExploreView: View {
+  @State private var searchQuery = ""
+  @State private var searchScope: SearchScope = .all
+  @State private var isSearching = false
+  @State private var results: [SearchResult] = []
+
+  var body: some View {
+    List {
+      if isSearching {
+        ProgressView()
+      } else {
+        ForEach(results) { result in
+          SearchRow(result: result)
+        }
+      }
+    }
+    .searchable(
+      text: $searchQuery,
+      placement: .navigationBarDrawer(displayMode: .always),
+      prompt: Text("Search")
+    )
+    .searchScopes($searchScope) {
+      ForEach(SearchScope.allCases, id: \.self) { scope in
+        Text(scope.title)
+      }
+    }
+    .task(id: searchQuery) {
+      await runSearch()
+    }
+  }
+
+  private func runSearch() async {
+    guard !searchQuery.isEmpty else {
+      results = []
+      return
+    }
+    isSearching = true
+    defer { isSearching = false }
+    try? await Task.sleep(for: .milliseconds(250))
+    results = await fetchResults(query: searchQuery, scope: searchScope)
+  }
+}
+```
+
+## Design choices to keep
+
+- Show a placeholder when search is empty or has no results.
+- Debounce input to avoid spamming the network.
+- Keep search state local to the view.
+
+## Pitfalls
+
+- Avoid running searches for empty strings.
+- Don’t block the main thread during fetch.

package/.local/skills/swiftui-ui-patterns/references/sheets.md

@@ -0,0 +1,155 @@
+# Sheets
+
+## Intent
+
+Use a centralized sheet routing pattern so any view can present modals without prop-drilling. This keeps sheet state in one place and scales as the app grows.
+
+## Core architecture
+
+- Define a `SheetDestination` enum that describes every modal and is `Identifiable`.
+- Store the current sheet in a router object (`presentedSheet: SheetDestination?`).
+- Create a view modifier like `withSheetDestinations(...)` that maps the enum to concrete sheet views.
+- Inject the router into the environment so child views can set `presentedSheet` directly.
+
+## Example: item-driven local sheet
+
+Use this when sheet state is local to one screen and does not need centralized routing.
+
+```swift
+@State private var selectedItem: Item?
+
+.sheet(item: $selectedItem) { item in
+  EditItemSheet(item: item)
+}
+```
+
+## Example: SheetDestination enum
+
+```swift
+enum SheetDestination: Identifiable, Hashable {
+  case composer
+  case editProfile
+  case settings
+  case report(itemID: String)
+
+  var id: String {
+    switch self {
+    case .composer, .editProfile:
+      // Use the same id to ensure only one editor-like sheet is active at a time.
+      return "editor"
+    case .settings:
+      return "settings"
+    case .report:
+      return "report"
+    }
+  }
+}
+```
+
+## Example: withSheetDestinations modifier
+
+```swift
+extension View {
+  func withSheetDestinations(
+    sheet: Binding<SheetDestination?>
+  ) -> some View {
+    sheet(item: sheet) { destination in
+      Group {
+        switch destination {
+        case .composer:
+          ComposerView()
+        case .editProfile:
+          EditProfileView()
+        case .settings:
+          SettingsView()
+        case .report(let itemID):
+          ReportView(itemID: itemID)
+        }
+      }
+    }
+  }
+}
+```
+
+## Example: presenting from a child view
+
+```swift
+struct StatusRow: View {
+  @Environment(RouterPath.self) private var router
+
+  var body: some View {
+    Button("Report") {
+      router.presentedSheet = .report(itemID: "123")
+    }
+  }
+}
+```
+
+## Required wiring
+
+For the child view to work, a parent view must:
+- own the router instance,
+- attach `withSheetDestinations(sheet: $router.presentedSheet)` (or an equivalent `sheet(item:)` handler), and
+- inject it with `.environment(router)` after the sheet modifier so the modal content inherits it.
+
+This makes the child assignment to `router.presentedSheet` drive presentation at the root.
+
+## Example: sheets that need their own navigation
+
+Wrap sheet content in a `NavigationStack` so it can push within the modal.
+
+```swift
+struct NavigationSheet<Content: View>: View {
+  var content: () -> Content
+
+  var body: some View {
+    NavigationStack {
+      content()
+        .toolbar { CloseToolbarItem() }
+    }
+  }
+}
+```
+
+## Example: sheet owns its actions
+
+Keep dismissal and confirmation logic inside the sheet when the actions belong to the modal itself.
+
+```swift
+struct EditItemSheet: View {
+  @Environment(\.dismiss) private var dismiss
+  @Environment(Store.self) private var store
+
+  let item: Item
+  @State private var isSaving = false
+
+  var body: some View {
+    VStack {
+      Button(isSaving ? "Saving..." : "Save") {
+        Task { await save() }
+      }
+    }
+  }
+
+  private func save() async {
+    isSaving = true
+    await store.save(item)
+    dismiss()
+  }
+}
+```
+
+## Design choices to keep
+
+- Centralize sheet routing so features can present modals without wiring bindings through many layers.
+- Use `sheet(item:)` to guarantee a single sheet is active and to drive presentation from the enum.
+- Group related sheets under the same `id` when they are mutually exclusive (e.g., editor flows).
+- Keep sheet views lightweight and composed from smaller views; avoid large monoliths.
+- Let sheets own their actions and call `dismiss()` internally instead of forwarding `onCancel` or `onConfirm` closures through many layers.
+
+## Pitfalls
+
+- Avoid mixing `sheet(isPresented:)` and `sheet(item:)` for the same concern; prefer a single enum.
+- Avoid `if let` inside a sheet body when the presentation state already carries the selected model; prefer `sheet(item:)`.
+- Do not store heavy state inside `SheetDestination`; pass lightweight identifiers or models.
+- If multiple sheets can appear from the same screen, give them distinct `id` values.

package/.local/skills/swiftui-ui-patterns/references/split-views.md

@@ -0,0 +1,72 @@
+# Split views and columns
+
+## Intent
+
+Provide a lightweight, customizable multi-column layout for iPad/macOS without relying on `NavigationSplitView`.
+
+## Custom split column pattern (manual HStack)
+
+Use this when you want full control over column sizing, behavior, and environment tweaks.
+
+```swift
+@MainActor
+struct AppView: View {
+  @Environment(\.horizontalSizeClass) private var horizontalSizeClass
+  @AppStorage("showSecondaryColumn") private var showSecondaryColumn = true
+
+  var body: some View {
+    HStack(spacing: 0) {
+      primaryColumn
+      if shouldShowSecondaryColumn {
+        Divider().edgesIgnoringSafeArea(.all)
+        secondaryColumn
+      }
+    }
+  }
+
+  private var shouldShowSecondaryColumn: Bool {
+    horizontalSizeClass == .regular
+      && showSecondaryColumn
+  }
+
+  private var primaryColumn: some View {
+    TabView { /* tabs */ }
+  }
+
+  private var secondaryColumn: some View {
+    NotificationsTab()
+      .environment(\.isSecondaryColumn, true)
+      .frame(maxWidth: .secondaryColumnWidth)
+  }
+}
+```
+
+## Notes on the custom approach
+
+- Use a shared preference or setting to toggle the secondary column.
+- Inject an environment flag (e.g., `isSecondaryColumn`) so child views can adapt behavior.
+- Prefer a fixed or capped width for the secondary column to avoid layout thrash.
+
+## Alternative: NavigationSplitView
+
+`NavigationSplitView` can handle sidebar + detail + supplementary columns for you, but is harder to customize in cases like:\n- a dedicated notification column independent of selection,\n- custom sizing, or\n- different toolbar behaviors per column.
+
+```swift
+@MainActor
+struct AppView: View {
+  var body: some View {
+    NavigationSplitView {
+      SidebarView()
+    } content: {
+      MainContentView()
+    } detail: {
+      NotificationsView()
+    }
+  }
+}
+```
+
+## When to choose which
+
+- Use the manual HStack split when you need full control or a non-standard secondary column.
+- Use `NavigationSplitView` when you want a standard system layout with minimal customization.