claudecode-omc 5.6.7 → 5.6.8

package/.local/skills/swiftui-expert-skill/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: swiftui-expert-skill
+description: Use when writing, reviewing, or refactoring SwiftUI code for iOS or macOS, including state management, view composition, performance, Liquid Glass adoption, or Instruments `.trace` capture/analysis for hangs, hitches, CPU hotspots, or
+  excessive view updates.
+---
+
+# SwiftUI Expert Skill
+
+## Operating Rules
+
+- Consult `references/latest-apis.md` at the start of every task to avoid deprecated APIs
+- Prefer native SwiftUI APIs over UIKit/AppKit bridging unless bridging is necessary
+- Focus on correctness and performance; do not enforce specific architectures (MVVM, VIPER, etc.)
+- Encourage separating business logic from views for testability without mandating how
+- Follow Apple's Human Interface Guidelines and API design patterns
+- Only adopt Liquid Glass when explicitly requested by the user (see `references/liquid-glass.md`)
+- Present performance optimizations as suggestions, not requirements
+- Use `#available` gating with sensible fallbacks for version-specific APIs
+
+## Task Workflow
+
+### Review existing SwiftUI code
+- Read the code under review and identify which topics apply
+- Flag deprecated APIs (compare against `references/latest-apis.md`)
+- Run the Topic Router below for each relevant topic
+- Validate `#available` gating and fallback paths for iOS 26+ features
+
+### Improve existing SwiftUI code
+- Audit current implementation against the Topic Router topics
+- Replace deprecated APIs with modern equivalents from `references/latest-apis.md`
+- Refactor hot paths to reduce unnecessary state updates
+- Extract complex view bodies into separate subviews
+- Suggest image downsampling when `UIImage(data:)` is encountered (optional optimization, see `references/image-optimization.md`)
+
+### Implement new SwiftUI feature
+- Design data flow first: identify owned vs injected state
+- Structure views for optimal diffing (extract subviews early)
+- Apply correct animation patterns (implicit vs explicit, transitions)
+- Use `Button` for all tappable elements; add accessibility grouping and labels
+- Gate version-specific APIs with `#available` and provide fallbacks
+
+### Record a new Instruments trace
+Trigger when the user asks to "record a trace", "profile the app", "capture a session", etc. Full reference: `references/trace-recording.md`.
+
+1. **Confirm target** — attach to a running app, launch an app, or record all processes? If the user didn't say, ask. List connected devices when useful:
+   ```bash
+   python3 "${SKILL_DIR}/scripts/record_trace.py" --list-devices
+   ```
+2. **Pick a template based on target kind** — the `SwiftUI` template populates the SwiftUI lane on any **real device**: a physical iOS/iPadOS device **or the host Mac**. The only exception is the **iOS Simulator**, where the SwiftUI lane comes back empty — switch to `--template "Time Profiler"` in that case (still gives Time Profiler + Hangs + Animation Hitches). Always check `--list-devices`: `simulators` kind → `Time Profiler`; `devices` kind (real devices and the host Mac) → default `SwiftUI`. Full decision table in `references/trace-recording.md`.
+3. **Start the recording**. For agent-driven sessions where the user says "I'll tell you when I'm done", start in the background and use a stop-file:
+   ```bash
+   python3 "${SKILL_DIR}/scripts/record_trace.py" \
+       --device "<name|udid>" --attach "<AppName>" \
+       --stop-file /tmp/stop-trace --output ~/Desktop/session.trace
+   ```
+   For interactive sessions, just tell the user to press Ctrl+C when done.
+4. **Signal stop** — when the user says they've finished exercising the app, `touch /tmp/stop-trace`. The script cleanly SIGINTs xctrace and waits up to 60s for finalisation.
+5. **Analyse** the resulting trace (flow into the "Trace-driven improvement" workflow below).
+
+### Trace-driven improvement (Instruments `.trace` provided)
+Trigger whenever the user's request references a `.trace` file. A target SwiftUI source file is **optional** — if given, cite specific lines; if not, recommend where to look based on view names and symbols the trace already reveals.
+
+Full reference: `references/trace-analysis.md`. Summary of the composition pattern:
+
+1. **Scope the analysis.** Ask yourself: does the user want the whole trace, or a slice?
+   - "focus on X / after X / between X and Y / during X" → **resolve to a window first** (see step 2).
+   - No scoping cue → analyse the whole trace.
+2. **Resolve a window (only if the user scoped).** The parser exposes two discovery modes:
+   ```bash
+   # Find a log that marks the start/end of the region of interest:
+   python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
+       --list-logs --log-message-contains "loaded feed" --log-limit 5
+   # Or list os_signpost intervals (paired begin/end), filterable by name:
+   python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
+       --list-signposts --signpost-name-contains "ImageDecode"
+   ```
+   Both modes accept `--window START_MS:END_MS` to scope discovery. Pick the `time_ms` (for logs) or `start_ms`/`end_ms` (for signposts) that match the user's description. Build a window like `--window 10400:11700`.
+3. **Run the main analysis** (with or without `--window`):
+   ```bash
+   python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
+       --json-only --top 10 [--window START_MS:END_MS]
+   ```
+4. **Interpret with `references/trace-analysis.md`** — key diagnostics:
+   - `main_running_coverage_pct` inside each correlation (<25% = blocked; ≥75% = CPU-bound).
+   - `swiftui-causes.top_sources` reveals *why* updates keep happening — high-edge-count sources like `UserDefaultObserver.send()` or wide `EnvironmentWriter` entries are structural invalidation bugs. Fixing one often collapses many downstream hot views.
+5. **When a specific view shows as expensive, ask who's invalidating it.** Use `--fanin-for "<view name>"` to get the ranked list of source nodes driving the updates.
+6. **Optionally ground in source.** If the user pointed at a file, read it and match view names / user-code symbols against identifiers there. If not, recommend which files to open based on the view names SwiftUI reported.
+7. **Return a prioritised plan.** Cite evidence (coverage %, hot symbol, overlapping view, log timestamp, cause-graph edges) and route each recommendation to a Topic Router reference.
+8. Only edit code if the user asked for edits.
+
+### Topic Router
+
+Consult the reference file for each topic relevant to the current task:
+
+| Topic | Reference |
+|-------|-----------|
+| State management | `references/state-management.md` |
+| View composition | `references/view-structure.md` |
+| Performance | `references/performance-patterns.md` |
+| Lists and ForEach | `references/list-patterns.md` |
+| Layout | `references/layout-best-practices.md` |
+| Sheets and navigation | `references/sheet-navigation-patterns.md` |
+| ScrollView | `references/scroll-patterns.md` |
+| Focus management | `references/focus-patterns.md` |
+| Animations (basics) | `references/animation-basics.md` |
+| Animations (transitions) | `references/animation-transitions.md` |
+| Animations (advanced) | `references/animation-advanced.md` |
+| Accessibility | `references/accessibility-patterns.md` |
+| Swift Charts | `references/charts.md` |
+| Charts accessibility | `references/charts-accessibility.md` |
+| Image optimization | `references/image-optimization.md` |
+| Liquid Glass (iOS 26+) | `references/liquid-glass.md` |
+| macOS scenes | `references/macos-scenes.md` |
+| macOS window styling | `references/macos-window-styling.md` |
+| macOS views | `references/macos-views.md` |
+| Text patterns | `references/text-patterns.md` |
+| Deprecated API lookup | `references/latest-apis.md` |
+| Instruments trace analysis | `references/trace-analysis.md` |
+| Instruments trace recording | `references/trace-recording.md` |
+
+## Correctness Checklist
+
+These are hard rules -- violations are always bugs:
+
+- [ ] `@State` properties are `private`
+- [ ] `@Binding` only where a child modifies parent state
+- [ ] Passed values never declared as `@State` or `@StateObject` (they ignore updates)
+- [ ] `@StateObject` for view-owned objects; `@ObservedObject` for injected
+- [ ] iOS 17+: `@State` with `@Observable`; `@Bindable` for injected observables needing bindings
+- [ ] `ForEach` uses stable identity (never `.indices` for dynamic content)
+- [ ] Constant number of views per `ForEach` element
+- [ ] `.animation(_:value:)` always includes the `value` parameter
+- [ ] `@FocusState` properties are `private`
+- [ ] No redundant `@FocusState` writes inside tap gesture handlers on `.focusable()` views
+- [ ] iOS 26+ APIs gated with `#available` and fallback provided
+- [ ] `import Charts` present in files using chart types
+
+## References
+
+- `references/latest-apis.md` -- **Read first for every task.** Deprecated-to-modern API transitions (iOS 15+ through iOS 26+)
+- `references/state-management.md` -- Property wrappers, data flow, `@Observable` migration
+- `references/view-structure.md` -- View extraction, container patterns, `@ViewBuilder`
+- `references/performance-patterns.md` -- Hot-path optimization, update control, `_logChanges()`
+- `references/list-patterns.md` -- ForEach identity, Table (iOS 16+), inline filtering pitfalls
+- `references/layout-best-practices.md` -- Layout patterns, GeometryReader alternatives
+- `references/accessibility-patterns.md` -- VoiceOver, Dynamic Type, grouping, traits
+- `references/animation-basics.md` -- Implicit/explicit animations, timing, performance
+- `references/animation-transitions.md` -- View transitions, `matchedGeometryEffect`, `Animatable`
+- `references/animation-advanced.md` -- Phase/keyframe animations (iOS 17+), `@Animatable` macro (iOS 26+)
+- `references/charts.md` -- Swift Charts marks, axes, selection, styling, Chart3D (iOS 26+)
+- `references/charts-accessibility.md` -- Charts VoiceOver, Audio Graph, fallback strategies
+- `references/sheet-navigation-patterns.md` -- Sheets, NavigationSplitView, Inspector
+- `references/scroll-patterns.md` -- ScrollViewReader, programmatic scrolling
+- `references/focus-patterns.md` -- Focus state, focusable views, focused values, default focus, common pitfalls
+- `references/image-optimization.md` -- AsyncImage, downsampling, caching
+- `references/liquid-glass.md` -- iOS 26+ Liquid Glass effects and fallback patterns
+- `references/macos-scenes.md` -- Settings, MenuBarExtra, WindowGroup, multi-window
+- `references/macos-window-styling.md` -- Toolbar styles, window sizing, Commands
+- `references/macos-views.md` -- HSplitView, Table, PasteButton, AppKit interop
+- `references/text-patterns.md` -- Text initializer selection, verbatim vs localized
+- `references/trace-analysis.md` -- Parse Instruments `.trace` files via `scripts/analyze_trace.py`; interpret main-thread coverage, high-severity SwiftUI updates, hitch narratives, and map findings back to source files
+- `references/trace-recording.md` -- Record a new trace via `scripts/record_trace.py`: attach to a running app, launch one fresh, or capture a manually-stopped session; supports stop-file for agent-driven flows

package/.local/skills/swiftui-expert-skill/references/accessibility-patterns.md

@@ -0,0 +1,215 @@
+# SwiftUI Accessibility Patterns Reference
+
+## Table of Contents
+
+- [Core Principle](#core-principle)
+- [Dynamic Type and @ScaledMetric](#dynamic-type-and-scaledmetric)
+- [Accessibility Traits](#accessibility-traits)
+- [Decorative Images](#decorative-images)
+- [Element Grouping](#element-grouping)
+- [Custom Controls](#custom-controls)
+- [Summary Checklist](#summary-checklist)
+
+## Core Principle
+
+Prefer `Button` over `onTapGesture` for tappable elements. `Button` provides VoiceOver support, focus handling, and proper traits for free.
+
+## Dynamic Type and @ScaledMetric
+
+System text styles scale with Dynamic Type automatically. Prefer built-in styles like `.largeTitle`, `.title`, `.title2`, `.title3`, `.headline`, `.subheadline`, `.body`, `.callout`, `.footnote`, `.caption`, and `.caption2` when they fit your UI:
+
+```swift
+VStack(alignment: .leading) {
+    Text("Inbox")
+        .font(.title2)
+    Text("3 unread messages")
+        .font(.body)
+    Text("Updated just now")
+        .font(.caption)
+}
+```
+
+For custom fonts, use a Dynamic Type-aware font initializer so the text still follows the user's preferred content size:
+
+```swift
+VStack(alignment: .leading) {
+    Text("Article")
+        .font(.custom("SourceSerif4-Semibold", size: 28, relativeTo: .title2))
+    Text("Body copy")
+        .font(.custom("SourceSerif4-Regular", size: 17))
+}
+```
+
+`Font.custom(_:size:relativeTo:)` lets you match a specific text style. `Font.custom(_:size:)` scales relative to the body style. Avoid fixed-size custom fonts for primary content that should respond to Dynamic Type.
+
+For non-text numeric values like padding, spacing, and image sizes, use `@ScaledMetric`:
+
+```swift
+struct ProfileHeader: View {
+    @ScaledMetric private var avatarSize = 60.0
+    @ScaledMetric private var spacing = 12.0
+
+    var body: some View {
+        HStack(spacing: spacing) {
+            Image("avatar")
+                .resizable()
+                .frame(width: avatarSize, height: avatarSize)
+            Text("Username")
+        }
+    }
+}
+```
+
+Specify a `relativeTo` text style when the value should track a specific Dynamic Type style, including for images or icons that should stay proportional to nearby text:
+
+```swift
+struct StatusRow: View {
+    @ScaledMetric(relativeTo: .body) private var iconSize = 18.0
+
+    var body: some View {
+        HStack(spacing: 8) {
+            Image(systemName: "checkmark.circle.fill")
+                .font(.system(size: iconSize))
+            Text("Synced")
+                .font(.custom("AvenirNext-Regular", size: 17, relativeTo: .body))
+        }
+    }
+}
+```
+
+## Accessibility Traits
+
+Use `accessibilityAddTraits` and `accessibilityRemoveTraits` for state-driven traits:
+
+```swift
+Text(item.title)
+    .accessibilityAddTraits(item.isSelected ? [.isSelected, .isButton] : .isButton)
+```
+
+Use `.disabled(true)` to make VoiceOver announce "Dimmed" for non-interactive elements.
+
+## Decorative Images
+
+Use `Image(decorative:bundle:)` when an asset image is purely visual and should not appear in the accessibility tree.
+
+```swift
+Image(decorative: "confetti")
+```
+
+This is appropriate for backgrounds, flourishes, and icons that do not add meaning beyond nearby text.
+
+If the image conveys information, keep it accessible and provide a clear label:
+
+```swift
+Image("receipt")
+    .accessibilityLabel("Receipt")
+```
+
+For non-asset images, such as SF Symbols, hide decorative content with `accessibilityHidden(true)` instead:
+
+```swift
+Image(systemName: "sparkles")
+    .accessibilityHidden(true)
+```
+
+## Element Grouping
+
+### .combine -- Auto-join child labels
+
+```swift
+HStack {
+    Image(systemName: "star.fill")
+    Text("Favorites")
+    Text("(\(count))")
+}
+.accessibilityElement(children: .combine)
+```
+
+VoiceOver reads all child labels as one element, separated by commas.
+
+### .ignore -- Manual label for container
+
+```swift
+HStack {
+    Text(item.name)
+    Spacer()
+    Text(item.price)
+}
+.accessibilityElement(children: .ignore)
+.accessibilityLabel("\(item.name), \(item.price)")
+```
+
+### .contain -- Semantic grouping
+
+```swift
+HStack {
+    ForEach(tabs) { tab in
+        TabButton(tab: tab)
+    }
+}
+.accessibilityElement(children: .contain)
+.accessibilityLabel("Tab bar")
+```
+
+VoiceOver announces the container name when focus enters/exits.
+
+## Custom Controls
+
+### Adjustable controls (increment/decrement)
+
+```swift
+PageControl(selectedIndex: $selectedIndex, pageCount: pageCount)
+    .accessibilityElement()
+    .accessibilityValue("Page \(selectedIndex + 1) of \(pageCount)")
+    .accessibilityAdjustableAction { direction in
+        switch direction {
+        case .increment:
+            guard selectedIndex < pageCount - 1 else { break }
+            selectedIndex += 1
+        case .decrement:
+            guard selectedIndex > 0 else { break }
+            selectedIndex -= 1
+        @unknown default:
+            break
+        }
+    }
+```
+
+### Representing custom views as native controls
+
+When a custom view should behave like a native control for accessibility:
+
+```swift
+HStack {
+    Text(label)
+    Toggle("", isOn: $isOn)
+}
+.accessibilityRepresentation {
+    Toggle(label, isOn: $isOn)
+}
+```
+
+### Label-content pairing
+
+```swift
+@Namespace private var ns
+
+HStack {
+    Text("Volume")
+        .accessibilityLabeledPair(role: .label, id: "volume", in: ns)
+    Slider(value: $volume)
+        .accessibilityLabeledPair(role: .content, id: "volume", in: ns)
+}
+```
+
+## Summary Checklist
+
+- [ ] Use `Button` instead of `onTapGesture` for tappable elements
+- [ ] Use built-in text styles or Dynamic Type-aware custom fonts for text
+- [ ] Use `@ScaledMetric` for custom values that should scale with Dynamic Type
+- [ ] Mark purely decorative images as decorative or hidden from accessibility
+- [ ] Group related elements with `accessibilityElement(children:)`
+- [ ] Provide `accessibilityLabel` when default labels are unclear
+- [ ] Use `accessibilityRepresentation` for custom controls
+- [ ] Use `accessibilityAdjustableAction` for increment/decrement controls
+- [ ] Ensure navigation flow is logical when using VoiceOver grouping