cctop: Skill for Claude Code

SwiftUI Debugging

Overview

Systematic approaches for debugging SwiftUI issues in macOS apps. Covers view updates, state ownership, performance, layout, and macOS-specific quirks with NSHostingView and NSPanel.

Logging in macOS Apps

print() and NSLog() are invisible when launching macOS apps from CLI or Finder (menubar-only apps have no console). Always use file-based logging:

func debugLog(_ message: String) {
    let entry = "\(Date()) \(message)\n"
    let url = URL(fileURLWithPath: "/tmp/debug.log")
    if let handle = try? FileHandle(forWritingTo: url) {
        handle.seekToEndOfFile()
        handle.write(entry.data(using: .utf8)!)
        handle.closeFile()
    } else {
        try? entry.write(to: url, atomically: true, encoding: .utf8)
    }
}

Remove all debug logging before committing. Use grep -r "debugLog" --include="*.swift" to verify.

View Not Updating

Symptom

View shows stale data after a confirmed state change. Common with hostingView.rootView = NewView(...) not propagating to children, or theme/color changes not reflecting.

Root Cause: SwiftUI Diffing

SwiftUI skips re-evaluating a child view's body if the child's struct inputs haven't changed — even if the child reads from a singleton or computed property that did change.

Parent: rootView = MyView(counts: same)
  → SwiftUI: "counts didn't change, skip child body"
  → Child: never re-reads StatusColors.working
  → Result: stale colors

Diagnosis

1. Log at the data source (model/manager) and at the view's body — confirm data changed but body wasn't called
2. Check if the view reads external state (singletons, managers) not passed through its struct inputs
3. Use Self._printChanges() at the top of body to see what SwiftUI thinks triggered (or didn't trigger) a re-evaluation

Fixes

Root Cause	Fix
Child reads external state not in its inputs	Pass a changing value and add .id(value) to force recreation
@State destroyed by .id() changes	Extract into @StateObject owned by parent above the .id() boundary
NSColor(name:) dynamic colors cached	Use .id() to force re-resolution
@Published changed but view doesn't update	Verify view uses @ObservedObject, not a plain property