agentleFS
st0012st0012/cctop/.agents/skills/swiftui-debugging/SKILL.md

swiftui-debugging

Skill151 starsChanged 3 months agoMITView on GitHub

Use when debugging SwiftUI issues in this macOS app — views not updating, layout problems, unnecessary re-renders, state ownership bugs, Preview crashes, or NSHostingView/NSPanel quirks. Covers both general SwiftUI debugging and macOS-specific patterns.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Remove all debug logging before committing.

    line 30
  2. Distinctive:

    Check if the view reads external state (singletons, managers) not passed through its struct inputs

    line 52
  3. Very specific:

    Use Self._printChanges() at the top of body to see what SwiftUI thinks triggered (or didn't trigger) a re-evaluation

    line 53
  4. Very specific:

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

    line 125
  5. Distinctive:

    Check the diagnostic in Xcode's canvas (click the error icon)

    line 166
  6. Distinctive:

    Use mock data that avoids file system, network, or singleton access

    line 168

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 CauseFix
Child reads external state not in its inputsPass a changing value and add .id(value) to force recreation
@State destroyed by .id() changesExtract into @StateObject owned by parent above the .id() boundary
NSColor(name:) dynamic colors cachedUse .id() to force re-resolution
@Published changed but view doesn't updateVerify 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

WrapperOwned byLifetimeUse when
@StateThe viewDies with view identity (.id())Simple value types internal to one view
@StateObjectThe view that creates itSurvives re-renders, dies with viewYou create the object and own its lifetime
@ObservedObjectSomeone elseYou don't control itPassed 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

ProblemFirst step
View shows stale dataSelf._printChanges() — is body even called?
View never re-rendersCheck property wrappers — @ObservedObject vs @StateObject
State resets unexpectedlyLook for .id() changes destroying @State
Can't see print outputUse file-based logging (/tmp/debug.log)
Layout wrong.border(Color.red) on suspect views
Preview crashesCheck for singleton/file access in init
NSHostingView children staleInputs unchanged → use .id() to force recreation
@MainActor errors everywhereAdd top-down from the root type, not bottom-up

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.