st0012/swiftui-debugging

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 |

.id() Force-Recreation

struct NotchStatusView: View {
    let counts: StatusCounts
    var themeId: String = ""  // changes when theme changes

    var body: some View {
        HStack { ... }
            .id(themeId)  // forces ALL children to recreate
    }
}

Tradeoff: .id() destroys the entire subtree including @State.

State Extraction (surviving .id())

// Move @State into @StateObject owned above the .id() boundary
class OverlayController: ObservableObject {
    @Published var active: Overlay?
}

struct ParentView: View {
    @StateObject private var controller = OverlayController()  // survives
    var body: some View {
        ChildView(controller: controller)
            .id(themeId)  // safe — controller lives here
    }
}

State Ownership Bugs

@State vs @StateObject vs @ObservedObject

| Wrapper | Owned by | Lifetime | Use when | |---------|----------|----------|----------| | @State | The view | Dies with view identity (.id()) | Simple value types internal to one view | | @StateObject | The view that creates it | Survives re-renders, dies with view | You create the object and own its lifetime | | @ObservedObject | Someone else | You don't control it | Passed in from parent, not owned here |

Common Bug: @ObservedObject with inline init

// BUG: creates new instance every re-render, losing state
struct MyView: View {
    @ObservedObject var model = MyModel()  // wrong — recreated each time
}

// FIX: use @StateObject for owned objects
struct MyView: View {
    @StateObject var model = MyModel()  // correct — created once
}

Unnecessary Re-renders

Diagnosis

Add Self._printChanges() at the top of body to see what SwiftUI thinks changed:

var body: some View {
    let _ = Self._printChanges()  // prints: "MyView: @self, _count changed."
    ...
}

Common Causes

• Struct not Equatable — SwiftUI can't diff, re-renders every time. Add Equatable conformance.
• Closure properties — closures aren't equatable; every parent render creates a new closure. Move closures to methods or use EquatableView.
• Overly broad @Published — publishing a large object when only one field changed. Break into granular publishers or use @Observable (macOS 14+).

Layout Debugging

Visual debugging

// Highlight view bounds
.border(Color.red)
.background(Color.blue.opacity(0.2))

// Check what size SwiftUI gives a view
.overlay(GeometryReader { geo in
    Text("\(Int(geo.size.width))×\(Int(geo.size.height))")
        .font(.caption2).foregroundColor(.red)
})

Common Layout Issues

• View collapses to zero — missing .frame() or parent doesn't propose a size. Check with background(Color.red).
• Text truncation — fixedSize() lets text exceed proposed size, or use lineLimit(nil).
• GeometryReader takes all space — it's greedy. Wrap in an explicit .frame() or use it only for reading, not sizing.

Preview Debugging

Preview crashes silently

• Check the diagnostic in Xcode's canvas (click the error icon)
• Previews run in a separate process — crashes in init() or computed properties won't show a stack trace
• Use mock data that avoids file system, network, or singleton access

Preview works but app doesn't (or vice versa)

• Previews use a different bundle — Bundle.main returns different values
• Previews may not have the same entitlements (e.g., no Automation permission)
• @AppStorage reads from a different UserDefaults suite in previews

macOS-Specific: NSHostingView and NSPanel

NSHostingView rootView replacement

Setting hostingView.rootView = NewView(...) does NOT recreate the view tree — SwiftUI diffs the old and new struct. If inputs are identical, children skip body evaluation. This is the most common source of "view not updating" bugs in macOS apps using NSHostingView.

NSPanel quirks

• needsDisplay = true on NSHostingView does nothing — SwiftUI manages its own display cycle
• orderOut(nil) hides but doesn't destroy the hosting view; state persists
• For clickable panels (e.g., notch pill), use NSPanel with styleMask: [.nonactivatingPanel] and override canBecomeKey to avoid stealing focus

@MainActor cascade

Making a type @MainActor (e.g., to access ThemeManager.shared) cascades to everything that uses it. Plan for this — it often requires @MainActor on models, renderers, controllers, and test classes. Add it top-down rather than chasing compiler errors bottom-up.

Quick Reference

| Problem | First step | |---------|-----------| | View shows stale data | Self._printChanges() — is body even called? | | View never re-renders | Check property wrappers — @ObservedObject vs @StateObject | | State resets unexpectedly | Look for .id() changes destroying @State | | Can't see print output | Use file-based logging (/tmp/debug.log) | | Layout wrong | .border(Color.red) on suspect views | | Preview crashes | Check for singleton/file access in init | | NSHostingView children stale | Inputs unchanged → use .id() to force recreation | | @MainActor errors everywhere | Add top-down from the root type, not bottom-up |