agy-superpowers 5.0.8 → 5.0.9

package/template/agent/skills/mobile-developer/references/ios-rules/view-structure.md

@@ -0,0 +1,389 @@
+# SwiftUI View Structure Reference
+
+## Table of Contents
+
+- [View Structure Principles](#view-structure-principles)
+- [Prefer Modifiers Over Conditional Views](#prefer-modifiers-over-conditional-views)
+- [Extract Subviews, Not Computed Properties](#extract-subviews-not-computed-properties)
+- [When @ViewBuilder Functions Are Acceptable](#when-viewbuilder-functions-are-acceptable)
+- [When to Extract Subviews](#when-to-extract-subviews)
+- [Container View Pattern](#container-view-pattern)
+- [ZStack vs overlay/background](#zstack-vs-overlaybackground)
+- [Compositing Group Before Clipping](#compositing-group-before-clipping)
+- [Reusable Styling with ViewModifier](#reusable-styling-with-viewmodifier)
+- [Skeleton Loading with Redacted Views](#skeleton-loading-with-redacted-views)
+- [UIViewRepresentable Essentials](#uiviewrepresentable-essentials)
+- [Summary Checklist](#summary-checklist)
+
+## View Structure Principles
+
+SwiftUI's diffing algorithm compares view hierarchies to determine what needs updating. Proper view composition directly impacts performance.
+
+## Prefer Modifiers Over Conditional Views
+
+**Prefer "no-effect" modifiers over conditionally including views.** When you introduce a branch, consider whether you're representing multiple views or two states of the same view.
+
+### Use Opacity Instead of Conditional Inclusion
+
+```swift
+// Good - same view, different states
+SomeView()
+    .opacity(isVisible ? 1 : 0)
+
+// Avoid - creates/destroys view identity
+if isVisible {
+    SomeView()
+}
+```
+
+**Why**: Conditional view inclusion can cause loss of state, poor animation performance, and breaks view identity. Using modifiers maintains view identity across state changes.
+
+### When Conditionals Are Appropriate
+
+Use conditionals when you truly have **different views**, not different states:
+
+```swift
+// Correct - fundamentally different views
+if isLoggedIn {
+    DashboardView()
+} else {
+    LoginView()
+}
+
+// Correct - optional content
+if let user {
+    UserProfileView(user: user)
+}
+```
+
+### Conditional View Modifier Extensions Break Identity
+
+A common pattern is an `if`-based `View` extension for conditional modifiers. This changes the view's return type between branches, which destroys view identity and breaks animations:
+
+```swift
+// Problematic -- different return types per branch
+extension View {
+    @ViewBuilder func `if`<T: View>(_ condition: Bool, transform: (Self) -> T) -> some View {
+        if condition {
+            transform(self)  // Returns T
+        } else {
+            self              // Returns Self
+        }
+    }
+}
+```
+
+Prefer applying the modifier directly with a ternary or always-present modifier:
+
+```swift
+// Good -- same view identity maintained
+Text("Hello")
+    .opacity(isHighlighted ? 1 : 0.5)
+
+// Good -- modifier always present, value changes
+Text("Hello")
+    .foregroundStyle(isError ? .red : .primary)
+```
+
+## Extract Subviews, Not Computed Properties
+
+### The Problem with @ViewBuilder Functions
+
+When you use `@ViewBuilder` functions or computed properties for complex views, the entire function re-executes on every parent state change:
+
+```swift
+// BAD - re-executes complexSection() on every tap
+struct ParentView: View {
+    @State private var count = 0
+
+    var body: some View {
+        VStack {
+            Button("Tap: \(count)") { count += 1 }
+            complexSection()  // Re-executes every tap!
+        }
+    }
+
+    @ViewBuilder
+    func complexSection() -> some View {
+        // Complex views that re-execute unnecessarily
+        ForEach(0..<100) { i in
+            HStack {
+                Image(systemName: "star")
+                Text("Item \(i)")
+                Spacer()
+                Text("Detail")
+            }
+        }
+    }
+}
+```
+
+### The Solution: Separate Structs
+
+Extract to separate `struct` views. SwiftUI can skip their `body` when inputs don't change:
+
+```swift
+// GOOD - ComplexSection body SKIPPED when its inputs don't change
+struct ParentView: View {
+    @State private var count = 0
+
+    var body: some View {
+        VStack {
+            Button("Tap: \(count)") { count += 1 }
+            ComplexSection()  // Body skipped during re-evaluation
+        }
+    }
+}
+
+struct ComplexSection: View {
+    var body: some View {
+        ForEach(0..<100) { i in
+            HStack {
+                Image(systemName: "star")
+                Text("Item \(i)")
+                Spacer()
+                Text("Detail")
+            }
+        }
+    }
+}
+```
+
+### Why This Works
+
+1. SwiftUI compares the `ComplexSection` struct (which has no properties)
+2. Since nothing changed, SwiftUI skips calling `ComplexSection.body`
+3. The complex view code never executes unnecessarily
+
+## When @ViewBuilder Functions Are Acceptable
+
+Use for small, simple sections (a few views, no expensive computation) that don't affect performance. `@ViewBuilder` functions work particularly well for static content that doesn't depend on any `@State` or `@Binding`, since SwiftUI won't need to diff them independently. Extract to a separate `struct` when the section is complex, depends on state, or needs to be skipped during re-evaluation.
+
+## When to Extract Subviews
+
+Extract complex views into separate subviews when:
+- The view has multiple logical sections or responsibilities
+- The view contains reusable components
+- The view body becomes difficult to read or understand
+- You need to isolate state changes for performance
+- The view is becoming large (keep views small for better performance)
+
+## Container View Pattern
+
+### Avoid Closure-Based Content
+
+Closures can't be compared, causing unnecessary re-renders:
+
+```swift
+// BAD - closure prevents SwiftUI from skipping updates
+struct MyContainer<Content: View>: View {
+    let content: () -> Content
+
+    var body: some View {
+        VStack {
+            Text("Header")
+            content()  // Always called, can't compare closures
+        }
+    }
+}
+
+// Usage forces re-render on every parent update
+MyContainer {
+    ExpensiveView()
+}
+```
+
+### Use @ViewBuilder Property Instead
+
+```swift
+// GOOD - view can be compared
+struct MyContainer<Content: View>: View {
+    @ViewBuilder let content: Content
+
+    var body: some View {
+        VStack {
+            Text("Header")
+            content  // SwiftUI can compare and skip if unchanged
+        }
+    }
+}
+
+// Usage - SwiftUI can diff ExpensiveView
+MyContainer {
+    ExpensiveView()
+}
+```
+
+## ZStack vs overlay/background
+
+Use `ZStack` to **compose multiple peer views** that should be layered together and jointly define layout.
+
+Prefer `overlay` / `background` when you’re **decorating a primary view**.  
+Not primarily because they don’t affect layout size, but because they **express intent and improve readability**: the view being modified remains the clear layout anchor.
+
+A key difference is **size proposal behavior**:
+- In `overlay` / `background`, the child view implicitly adopts the size proposed to the parent when it doesn’t define its own size, making decorative attachments feel natural and predictable.
+- In `ZStack`, each child participates independently in layout, and no implicit size inheritance exists. This makes it better suited for peer composition, but less intuitive for simple decoration.
+
+Use `ZStack` (or another container) when the “decoration” **must explicitly participate in layout sizing**—for example, when reserving space, extending tappable/visible bounds, or preventing overlap with neighboring views.
+
+### Examples
+
+```swift
+// GOOD - decoration via overlay (layout anchored to button)
+Button("Continue") { }
+    .overlay(alignment: .trailing) {
+        Image(systemName: "lock.fill").padding(.trailing, 8)
+    }
+
+// BAD - ZStack when overlay suffices (layout no longer anchored to button)
+ZStack(alignment: .trailing) {
+    Button("Continue") { }
+    Image(systemName: "lock.fill").padding(.trailing, 8)
+}
+
+// GOOD - background shape takes parent size
+HStack(spacing: 12) { Text("Inbox"); Text("Next") }
+    .background { Capsule().strokeBorder(.blue, lineWidth: 2) }
+```
+
+## Compositing Group Before Clipping
+
+**Always add `.compositingGroup()` before `.clipShape()` when clipping layered views (`.overlay` or `.background`).** Without it, each layer is antialiased separately and then composited. Where antialiased edges overlap — typically at rounded corners — you get visible color fringes (semi-transparent pixels of different colors blending together).
+
+```swift
+let shape = RoundedRectangle(cornerRadius: 16)
+
+// BAD - each layer antialiased separately, producing color fringes at corners
+Color.red
+    .overlay(.white, in: shape)
+    .clipShape(shape)
+    .frame(width: 200, height: 150)
+
+// GOOD - layers composited first, antialiasing applied once during clipping
+Color.red
+    .overlay(.white, in: .rect)
+    .compositingGroup()
+    .clipShape(shape)
+    .frame(width: 200, height: 150)
+```
+
+`.compositingGroup()` forces all child layers to be rendered into a single offscreen buffer before the clip is applied. This means antialiasing only happens once — on the final composited result — eliminating the fringe artifacts.
+
+## Reusable Styling with ViewModifier
+
+Extract repeated modifier combinations into a `ViewModifier` struct. Expose via a `View` extension for autocompletion:
+
+```swift
+private struct CardStyle: ViewModifier {
+    func body(content: Content) -> some View {
+        content
+            .padding()
+            .background(Color(.secondarySystemBackground))
+            .clipShape(.rect(cornerRadius: 12))
+    }
+}
+
+extension View {
+    func cardStyle() -> some View {
+        modifier(CardStyle())
+    }
+}
+```
+
+### Custom ButtonStyle
+
+Use the `ButtonStyle` protocol for reusable button designs. Use `PrimitiveButtonStyle` only when you need custom interaction handling (e.g., simultaneous gestures):
+
+```swift
+struct PrimaryButtonStyle: ButtonStyle {
+    func makeBody(configuration: Configuration) -> some View {
+        configuration.label
+            .bold()
+            .foregroundStyle(.white)
+            .padding(.horizontal, 16)
+            .padding(.vertical, 8)
+            .background(Color.accentColor)
+            .clipShape(Capsule())
+            .scaleEffect(configuration.isPressed ? 0.95 : 1)
+            .animation(.smooth, value: configuration.isPressed)
+    }
+}
+```
+
+### Discoverability with Static Member Lookup
+
+Make custom styles and modifiers discoverable via leading-dot syntax:
+
+```swift
+extension ButtonStyle where Self == PrimaryButtonStyle {
+    static var primary: PrimaryButtonStyle { .init() }
+}
+
+// Usage: .buttonStyle(.primary)
+```
+
+This pattern works for any SwiftUI style protocol (`ButtonStyle`, `ListStyle`, `ToggleStyle`, etc.).
+
+## Skeleton Loading with Redacted Views
+
+Use `.redacted(reason: .placeholder)` to show skeleton views while data loads. Use `.unredacted()` to opt out specific views:
+
+```swift
+VStack(alignment: .leading) {
+    Text(article?.title ?? String(repeating: "X", count: 20))
+        .font(.headline)
+    Text(article?.author ?? String(repeating: "X", count: 12))
+        .font(.subheadline)
+    Text("SwiftLee")
+        .font(.caption)
+        .unredacted()
+}
+.redacted(reason: article == nil ? .placeholder : [])
+```
+
+Apply `.redacted` on a container to redact all children at once.
+
+## UIViewRepresentable Essentials
+
+When bridging UIKit views into SwiftUI:
+
+- `makeUIView(context:)` is called **once** to create the UIKit view
+- `updateUIView(_:context:)` is called on **every SwiftUI redraw** to sync state
+- The representable struct itself is **recreated on every redraw** -- avoid heavy work in its init
+- Use a `Coordinator` for delegate callbacks and two-way communication
+
+```swift
+struct MapView: UIViewRepresentable {
+    let coordinate: CLLocationCoordinate2D
+
+    func makeUIView(context: Context) -> MKMapView {
+        let map = MKMapView()
+        map.delegate = context.coordinator
+        return map
+    }
+
+    func updateUIView(_ map: MKMapView, context: Context) {
+        map.setCenter(coordinate, animated: true)
+    }
+
+    func makeCoordinator() -> Coordinator { Coordinator() }
+
+    class Coordinator: NSObject, MKMapViewDelegate { }
+}
+```
+
+## Summary Checklist
+
+- [ ] Prefer modifiers over conditional views for state changes
+- [ ] Avoid `if`-based conditional modifier extensions (they break view identity)
+- [ ] Complex views extracted to separate subviews
+- [ ] Views kept small for better performance
+- [ ] `@ViewBuilder` functions only for simple sections
+- [ ] Container views use `@ViewBuilder let content: Content`
+- [ ] Extract views when they have multiple responsibilities or become hard to read
+- [ ] Reusable styling extracted into `ViewModifier` or `ButtonStyle`
+- [ ] Custom styles exposed via static member lookup for discoverability
+- [ ] Use `.redacted(reason: .placeholder)` for skeleton loading states
+- [ ] `.compositingGroup()` before `.clipShape()` on layered views (overlay/background) to avoid antialiasing fringes
+- [ ] UIViewRepresentable: heavy work in make/update, not in struct init

package/template/agent/skills/mobile-developer/references/react-native-rules/_sections.md

@@ -0,0 +1,86 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Core Rendering (rendering)
+
+**Impact:** CRITICAL  
+**Description:** Fundamental React Native rendering rules. Violations cause
+runtime crashes or broken UI.
+
+## 2. List Performance (list-performance)
+
+**Impact:** HIGH  
+**Description:** Optimizing virtualized lists (FlatList, LegendList, FlashList)
+for smooth scrolling and fast updates.
+
+## 3. Animation (animation)
+
+**Impact:** HIGH  
+**Description:** GPU-accelerated animations, Reanimated patterns, and avoiding
+render thrashing during gestures.
+
+## 4. Scroll Performance (scroll)
+
+**Impact:** HIGH  
+**Description:** Tracking scroll position without causing render thrashing.
+
+## 5. Navigation (navigation)
+
+**Impact:** HIGH  
+**Description:** Using native navigators for stack and tab navigation instead of
+JS-based alternatives.
+
+## 6. React State (react-state)
+
+**Impact:** MEDIUM  
+**Description:** Patterns for managing React state to avoid stale closures and
+unnecessary re-renders.
+
+## 7. State Architecture (state)
+
+**Impact:** MEDIUM  
+**Description:** Ground truth principles for state variables and derived values.
+
+## 8. React Compiler (react-compiler)
+
+**Impact:** MEDIUM  
+**Description:** Compatibility patterns for React Compiler with React Native and
+Reanimated.
+
+## 9. User Interface (ui)
+
+**Impact:** MEDIUM  
+**Description:** Native UI patterns for images, menus, modals, styling, and
+platform-consistent interfaces.
+
+## 10. Design System (design-system)
+
+**Impact:** MEDIUM  
+**Description:** Architecture patterns for building maintainable component
+libraries.
+
+## 11. Monorepo (monorepo)
+
+**Impact:** LOW  
+**Description:** Dependency management and native module configuration in
+monorepos.
+
+## 12. Third-Party Dependencies (imports)
+
+**Impact:** LOW  
+**Description:** Wrapping and re-exporting third-party dependencies for
+maintainability.
+
+## 13. JavaScript (js)
+
+**Impact:** LOW  
+**Description:** Micro-optimizations like hoisting expensive object creation.
+
+## 14. Fonts (fonts)
+
+**Impact:** LOW  
+**Description:** Native font loading for improved performance.

package/template/agent/skills/mobile-developer/references/react-native-rules/_template.md

@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)

package/template/agent/skills/mobile-developer/references/react-native-rules/animation-derived-value.md

@@ -0,0 +1,53 @@
+---
+title: Prefer useDerivedValue Over useAnimatedReaction
+impact: MEDIUM
+impactDescription: cleaner code, automatic dependency tracking
+tags: animation, reanimated, derived-value
+---
+
+## Prefer useDerivedValue Over useAnimatedReaction
+
+When deriving a shared value from another, use `useDerivedValue` instead of
+`useAnimatedReaction`. Derived values are declarative, automatically track
+dependencies, and return a value you can use directly. Animated reactions are
+for side effects, not derivations.
+
+**Incorrect (useAnimatedReaction for derivation):**
+
+```tsx
+import { useSharedValue, useAnimatedReaction } from 'react-native-reanimated'
+
+function MyComponent() {
+  const progress = useSharedValue(0)
+  const opacity = useSharedValue(1)
+
+  useAnimatedReaction(
+    () => progress.value,
+    (current) => {
+      opacity.value = 1 - current
+    }
+  )
+
+  // ...
+}
+```
+
+**Correct (useDerivedValue):**
+
+```tsx
+import { useSharedValue, useDerivedValue } from 'react-native-reanimated'
+
+function MyComponent() {
+  const progress = useSharedValue(0)
+
+  const opacity = useDerivedValue(() => 1 - progress.get())
+
+  // ...
+}
+```
+
+Use `useAnimatedReaction` only for side effects that don't produce a value
+(e.g., triggering haptics, logging, calling `runOnJS`).
+
+Reference:
+[Reanimated useDerivedValue](https://docs.swmansion.com/react-native-reanimated/docs/core/useDerivedValue)

package/template/agent/skills/mobile-developer/references/react-native-rules/animation-gesture-detector-press.md

@@ -0,0 +1,95 @@
+---
+title: Use GestureDetector for Animated Press States
+impact: MEDIUM
+impactDescription: UI thread animations, smoother press feedback
+tags: animation, gestures, press, reanimated
+---
+
+## Use GestureDetector for Animated Press States
+
+For animated press states (scale, opacity on press), use `GestureDetector` with
+`Gesture.Tap()` and shared values instead of Pressable's
+`onPressIn`/`onPressOut`. Gesture callbacks run on the UI thread as worklets—no
+JS thread round-trip for press animations.
+
+**Incorrect (Pressable with JS thread callbacks):**
+
+```tsx
+import { Pressable } from 'react-native'
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+  const scale = useSharedValue(1)
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ scale: scale.value }],
+  }))
+
+  return (
+    <Pressable
+      onPress={onPress}
+      onPressIn={() => (scale.value = withTiming(0.95))}
+      onPressOut={() => (scale.value = withTiming(1))}
+    >
+      <Animated.View style={animatedStyle}>
+        <Text>Press me</Text>
+      </Animated.View>
+    </Pressable>
+  )
+}
+```
+
+**Correct (GestureDetector with UI thread worklets):**
+
+```tsx
+import { Gesture, GestureDetector } from 'react-native-gesture-handler'
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming,
+  interpolate,
+  runOnJS,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+  // Store the press STATE (0 = not pressed, 1 = pressed)
+  const pressed = useSharedValue(0)
+
+  const tap = Gesture.Tap()
+    .onBegin(() => {
+      pressed.set(withTiming(1))
+    })
+    .onFinalize(() => {
+      pressed.set(withTiming(0))
+    })
+    .onEnd(() => {
+      runOnJS(onPress)()
+    })
+
+  // Derive visual values from the state
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { scale: interpolate(withTiming(pressed.get()), [0, 1], [1, 0.95]) },
+    ],
+  }))
+
+  return (
+    <GestureDetector gesture={tap}>
+      <Animated.View style={animatedStyle}>
+        <Text>Press me</Text>
+      </Animated.View>
+    </GestureDetector>
+  )
+}
+```
+
+Store the press **state** (0 or 1), then derive the scale via `interpolate`.
+This keeps the shared value as ground truth. Use `runOnJS` to call JS functions
+from worklets. Use `.set()` and `.get()` for React Compiler compatibility.
+
+Reference:
+[Gesture Handler Tap Gesture](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture)